Praxis Wiki logo

Direct API {wallet-token}


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

This API supports various transaction types for Alternative Payment Methods (APMs):

  • {authorization} lets you verify the availability of funds in the customer’s APM account and reserves the amount for a potential transaction.
  • {sale} allows you to receive payments from customers using APMs.
  • {payout} enables fund transfers from your merchant account to a customer’s account, either as part of a withdrawal request or a refund via APM.

In addition, the following webhook is available to keep your system up-to-date asynchronously:

  • Notification is triggered each time the transaction status changes.

{danger.fa-exclamation} IMPORTANT: 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.

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

Endpoints

Name URL
Sandbox https://pci-gw-test.praxispay.com/direct/wallet-token
Live https://gw.praxisgate.com/direct/wallet-token

Request Parameters

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

Variable Type 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).
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.
wallet_token varchar(32) HASH value of customer's wallet.
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 identit.
gateway varchar(32) ? ? APM gateway doing the processing.

The gateway parameter specifies the primary APM gateway to be used for processing.

Required when sending a request without payment_method parameter.

Optional when sending a request with payment_method parameter.
payment_method varchar(50) ? ? Payment method.

The payment_method parameter allows for overriding the specific gateway parameter, when utilizing features such as Cascading (for sale) or WD Routing Rules (for payout), for payment methods that support these options.

If both parameters gateway and payment_method received, the gateway value will be selected for 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 . To have the payout amount deducted from the related withdrawal request, send the tid of that withdrawal request.
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. wallet_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,
    "wallet_token": "wxtDmu8trYHrMWnpoBsEoq6YxqNxAsP-",
    "cid": "1",
    "locale": "en-GB",
    "customer_token": "87cfb23a8f1e68e162c276b754d9c061",
    "payment_method": "WireOnline",
    "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.0,
        "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
    },
    "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": "WireOnline",
        "payment_processor": "WireOnline Processor",
        "gateway": "s-pTSZyK23E1Ee5KZpcNbX_aFl0HuhQ0",
        "card": null,
        "wallet": {
            "wallet_token": "wxtDmu8trYHrMWnpoBsEoq6YxqNxAsP-",
            "wallet_data": {
                "full_name": "John Johnson",
                "bank_account": "11112222333344",
                "bank_name": "Random Bank, London",
                "bank_code": "AABBCC",
                "iban": "GB999911112222333344"
            }
        },
        "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.0,
        "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
    },
    "transaction": {
        "transaction_type": "sale",
        "transaction_status": "approved",
        "tid": 756850,
        "transaction_id": "13348",
        "currency": "EUR",
        "amount": 100,
        "conversion_rate": 1.0,
        "processed_currency": "EUR",
        "processed_amount": 100,
        "fee": 0,
        "fee_included": 0,
        "fee_type": "flat",
        "payment_method": "WireOnline",
        "payment_processor": "WireOnline Processor",
        "gateway": "s-pTSZyK23E1Ee5KZpcNbX_aFl0HuhQ0",
        "card": null,
        "wallet": {
            "wallet_token": "wxtDmu8trYHrMWnpoBsEoq6YxqNxAsP-",
            "wallet_data": {
                "full_name": "John Johnson",
                "bank_account": "11112222333344",
                "bank_name": "Random Bank, London",
                "bank_code": "AABBCC",
                "iban": "GB999911112222333344"
            }
        },
        "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.0,
        "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
    },
    "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": "WireOnline",
        "payment_processor": "WireOnline Processor",
        "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
}