Praxis Wiki logo

Direct API {card-token}


The Token Processing API enables you to process deposits and payouts over REST API using previously stored customer and payment detail tokens.
The key benefit of this API is that you do not need to transmit or collect sensitive information from the customer during the transaction.

The API supports the following transaction types:

  • {authorization} allows you to receive card payments from customers.
  • {sale} allows you to receive card payments from customers.
  • {payout} allows you to transfer funds from your merchant account to the customer’s card.

In addition, the following webhooks are available to help you stay updated asynchronously:

  • Notification is triggered every time the transaction status changes.

{danger.fa-exclamation} IMPORTANT 1: Currency conversion is not supported in Direct API. The filter currency and processing currency must always match.
This means that the currency sent to Praxis in a sale, payout, or refund request will be passed unchanged to the PSP for processing.


{danger.fa-exclamation} IMPORTANT 2: The customer_data or customer_token must be present in the request.

We use CryptoCompare for cryptocurrency rates, and Open Exchange Rates for FIAT currency rates.
Rates are updated every 15 minutes for crypto, and every 5 minutes for FIAT.

Endpoints

Name URL
Sandbox (PraxisGate) https://pci-gw-test.praxispay.com/api/direct-process
Live (PraxisGate) https://gw.praxisgate.com/api/direct-process

If your CRM does not technically support two separate domains as endpoints, the solution is to use a single domain for all API calls.

Example:
For the live environment, you should use https://gw.praxisgate.com instead of https://gateway.praxispay.com.
As a result, the endpoint becomes: https://gw.praxisgate.com/cashier/cashier.

image

Request Parameters

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

Variable Type auth sale payout Description
merchant_id varchar(50) Merchant API client account identifier.
application_key varchar(32) Identifier of your application (website).
transaction_type varchar(32) Transaction type. Allowed values are:
- authorization for authorization (allocate funds for later capture).
- sale for payment.
- payout for payout (CFT).
bdcc int(1) ? ? Background dynamic currency conversion. Allowed values are:
- 1 is enabled
- 0 is disabled (default)

Note 1: This parameter can be used to decide how to process given prior knowledge of the gateways available for processing and bdcc support for each, by using it in conjunction with get-available-gateways API.

Note 2: This option is only supported for cascade and cannot be used in conjunction with specifying a gateway (hash). In case of using a gateway hash, please specify a supported processing currency. You can use the get-available-gateways API to determine supported currencies.
currency varchar(10) Transaction currency.
amount int(20) Transaction amount in cents.
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.
card_token varchar(32) HASH value of customer's card.

Should not be included for Subsequent MIT requests.
mit <Object> ? ? MIT object will contain the list of settings for processing merchant-initiated transactions (MIT).
cvv_encrypted varchar(32) Card security code encrypted with aes-256-cbc, algorithm for encryption. Card Data (Encrypted)
device_data <Object> ? ? ? Device data object
three_ds_mpi_result <Object> ? ? Three DS MPI Result object
Results of 3DS Authentication
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_token varchar(32) ? ? ? HASH value of customer's identity.

Note: Either customer_token or customer_data must be provided. If both are missing, the request will trigger a validation error.
customer_data <Object> ? ? ? Customer data object
gateway varchar(32) ? ? Gateway doing the processing.
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.
withdrawal_request_id int(11) ? Original transaction identifier from . Send the tid of withdrawal request if you want the payout amount to be deducted from withdrawal request as processed.
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.
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.
redirect_url varchar(256) ? 3D Secure verification URL or e-wallet login URL. Appears only in combination with "transaction_status":"initialized".
customer <Object> Customer object
session <Object> Session object
transaction <Object> Transaction 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. transaction_type
  5. cid
  6. order_id
  7. currency
  8. amount
  9. gateway
  10. notification_url
  11. return_url
  12. card_token

Response signature parameters

  1. status
  2. timestamp
  3. redirect_url
  4. customer.customer_token
  5. transaction.tid
  6. transaction.transaction_status
  7. transaction.processed_currency
  8. transaction.processed_amount

Example

Request

{
    "merchant_id": "Test-Integration-Merchant",
    "application_key": "Sandbox",
    "transaction_type": "sale",
    "currency": "EUR",
    "amount": 100,
    "card_token": "J-4-a0vPhjZ9R75JP98VDUFgbh9y8sYr",
    "cvv_encrypted": "V4tcWxPLaNA0emSKPsObnw==",
    "device_data": {
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Safari/605.1.15",
        "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
        "language": "en-us",
        "ip_address": "127.0.0.1",
        "timezone_offset": -180,
        "color_depth": "24",
        "pixel_depth": "24",
        "pixel_ratio": "2",
        "screen_height": 900,
        "screen_width": 1440,
        "viewport_height": 400,
        "viewport_width": 1440,
        "java_enabled": 0,
        "javascript_enabled": 1
    },
    "three_ds_mpi_result": {
        "three_ds_server_trans_id": "1w111036-4abf-4b50-9cd6-e593b0218ed5",
        "acs_trans_id": "2d551036-4abf-4b50-9cd6-e593b0218ed5",
        "authentication_type": "01",
        "trans_status": "Y",
        "acs_challenge_mandated": "N",
        "challenge_indicator": "05",
        "ds_trans_id": "62453bce-2714-40e4-9c00-0aa98541682a",
        "eci": "05",
        "transaction_status_reason": "17",
        "authentication_value": "MTIRWG9SWWRpU2I1M21DelozSTA=",
        "message_version": "2.2.0",
        "exemption_flag": "01",
        "channel": "02"
    },
    "mit": {
        "type": "initial",
        "expiry": 365
    },
    "cid": "1",
    "locale": "en-GB",
    "customer_token": "87cfb23a8f1e68e162c276b754d9c061",
    "gateway": "s-pTSZyK23E1Ee5KZpcNbX_aFl0HuhQ0",
    "notification_url": "https://api.merchant.com/v1/deposits/tx-1560610955",
    "return_url": "https://merchant.com/payment_result/tx-1560610955",
    "order_id": "test-1560610955",
    "withdrawal_request_id": null,
    "variable1": "your variable",
    "variable2": "if that is not enough, you can pass even one more variable",
    "variable3": null,
    "version": "1.3",
    "timestamp": 1590611635
    }

Response (3D Secure)

{
    "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": "Credit Card",
        "gateway": null,
        "cid": "1",
        "variable1": "your variable",
        "variable2": "if that is not enough, you can pass even one more variable",
        "variable3": null
    },
    "transaction": {
        "transaction_type": "sale",
        "transaction_status": "initialized",
        "tid": 756850,
        "transaction_id": "13348",
        "currency": "EUR",
        "amount": 100,
        "conversion_rate": null,
        "processed_currency": null,
        "processed_amount": null,
        "fee": 0,
        "fee_included": 0,
        "fee_type": "flat",
        "payment_method": "Credit Card",
        "payment_processor": "TestCardProcessor",
        "gateway": "s-pTSZyK23E1Ee5KZpcNbX_aFl0HuhQ0",
        "card": {
            "card_token": "J-4-a0vPhjZ9R75JP98VDUFgbh9y8sYr",
            "card_type": "VISA",
            "card_number": "411111******1111",
            "card_exp": "12\/2024",
            "card_issuer_name": "Bank of Somewhere",
            "card_issuer_country": "GB"
        },
        "mit": {
          "type": "initial",
          "expiry": 365
        },
        "wallet": null,
        "is_async": 1,
        "is_cascade": 0,
        "cascade_level": 0,
        "reference_id": null,
        "withdrawal_request_id": null,
        "account_identifier": null,
        "created_by": "INTERNET",
        "edited_by": "INTERNET",
        "status_code": "SC-001",
        "status_details": "Redirect to acquirer page"
    },
    "version": "1.3",
    "timestamp": 1590611635
}

Response (Approved)

{
    "status": 0,
    "description": "Ok",
    "redirect_url": null,
    "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": "Credit Card",
        "gateway": null,
        "cid": "1",
        "variable1": "your variable",
        "variable2": "if that is not enough, you can pass even one more variable",
        "variable3": null
    },
    "transaction": {
        "transaction_type": "sale",
        "transaction_status": "approved",
        "tid": 756850,
        "transaction_id": "13348",
        "currency": "EUR",
        "amount": 100,
        "conversion_rate": 1.000000,
        "processed_currency": "EUR",
        "processed_amount": 100,
        "fee": 0,
        "fee_included": 0,
        "fee_type": "flat",
        "payment_method": "Credit Card",
        "payment_processor": "TestCardProcessor",
        "gateway": "s-pTSZyK23E1Ee5KZpcNbX_aFl0HuhQ0",
        "card": {
            "card_token": "J-4-a0vPhjZ9R75JP98VDUFgbh9y8sYr",
            "card_type": "VISA",
            "card_number": "411111******1111",
            "card_exp": "12\/2024",
            "card_issuer_name": "Bank of Somewhere",
            "card_issuer_country": "GB"
        },
        "mit": {
            "type": "initial",
            "expiry": 365
        },
        "wallet": null,
        "is_async": 0,
        "is_cascade": 0,
        "cascade_level": 0,
        "reference_id": null,
        "withdrawal_request_id": null,
        "account_identifier": null,
        "created_by": "INTERNET",
        "edited_by": "INTERNET",
        "status_code": "SC-002",
        "status_details": "Transaction approved"
    },
    "version": "1.3",
    "timestamp": 1590611635
}

Response (Rejected)

{
    "status": 0,
    "description": "Ok",
    "redirect_url": null,
    "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": "Credit Card",
        "gateway": null,
        "cid": "1",
        "variable1": "your variable",
        "variable2": "if that is not enough, you can pass even one more variable",
        "variable3": null
    },
    "transaction": {
        "transaction_type": "sale",
        "transaction_status": "rejected",
        "tid": 756850,
        "transaction_id": "13348",
        "currency": "EUR",
        "amount": 100,
        "conversion_rate": null,
        "processed_currency": null,
        "processed_amount": null,
        "fee": 0,
        "fee_included": 0,
        "fee_type": "flat",
        "payment_method": "Credit Card",
        "payment_processor": "TestCardProcessor",
        "gateway": "s-pTSZyK23E1Ee5KZpcNbX_aFl0HuhQ0",
        "card": null,
        "wallet": null,
        "is_async": 0,
        "is_cascade": 0,
        "cascade_level": 0,
        "reference_id": null,
        "withdrawal_request_id": null,
        "account_identifier": null,
        "created_by": "INTERNET",
        "edited_by": "INTERNET",
        "status_code": "GE-001",
        "status_details": "Do not honor"
    },
    "version": "1.3",
    "timestamp": 1590611635
}