Praxis Wiki

Direct API `{card}`

ENDPOINTS
CHECKLIST
REQUEST PARAMETERS
RESPONSE PARAMETERS
SIGNATURE
EXAMPLE

Direct Card Processing API lets you process the credit and debit card deposits and payouts over REST API. In simple words, with this API the merchant will perform the card data collection on his side.

There are several transaction types supported by the API:
- {authorization} lets you receive the card payments from customers;
- {sale} lets you receive the card payments from customers;
- {payout} is a fund transfer from your merchant account to customer's card;
successful deposit;

In addition, the following webhooks are available in order to stay up-to-date with the updates asynchronously:
- Notification will be triggered each time that the transaction status changes;

{danger.fa-exclamation} IMPORTANT #1: In order to use the Direct API with full credit card details the merchant has to comply with PCI DSS and confirm their compliance level by providing the up-to-date AOC (Attestation of Compliance) document or SAQ-D with external vulnerability scan report.

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

{danger.fa-exclamation} IMPORTANT #3: Direct API does not support conversion, meaning that filter currency and processing currency must always match. It means the currency sent to Praxis within the Direct API sale, payout or refund call will be the same currency as we send to PSPs for processing.

We are using Cryptocurrency Prices, Portfolio, Forum, Rankings for crypto currencies, and Open Exchange Rates for FIAT currencies. The rates information is updated every 15 minutes.

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 domains as the endpoints, the solution is to use one domain intead for any API calls. Sandbox: https://pci-gw-test.praxispay.com, Live: https://gw.praxisgate.com

E.g. For Live: you need to use https://gw.praxisgate.com to substitute https://gateway.praxispay.com,
as a result - https://gw.praxisgate.com/cashier/cashier.

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. 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
card_data	<Object>	✓	✓	✓	Card data object (Encrypted) Card data can also be sent in an open format (please note: method in an open format is less secure and not supported by HPF) - Card data object (Decrypted). Should not be included for Subsequent MIT requests.
mit	<Object>	?	?	✕	MIT object will contain the list of settings for processing merchant-initiated transactions (MIT).
device_data	<Object>	✓	✓	?	Device data object (Some PSPs require the device data for payouts)
cid	varchar(50)	✓	✓	✓	Unique customer id in your system
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
gateway	varchar(32)	?	?	✓	Credit card 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 (Please note that if you wish to set/ update a user’s profile - the needed information needs to be passed in customer_data “profile” parameter)
variable2	varchar(256)	?	?	?	Your custom field to tag the transaction with some necessary information (Please note that if you wish to set/ update a user’s profile - the needed information needs to be passed in customer_data “profile” parameter)
variable3	varchar(256)	?	?	?	Your custom field to tag the transaction with some necessary information (Please note that if you wish to set/ update a user’s profile - the needed information needs to be passed in customer_data “profile” parameter)
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

merchant_id
application_key
timestamp
transaction_type
cid
order_id
currency
amount
gateway
notification_url
return_url
card_data.card_number (or card_data.hpf_auth_token in case of HPF)

Response signature parameters

status
timestamp
redirect_url
customer.customer_token
transaction.tid
transaction.transaction_status
transaction.processed_currency
transaction.processed_amount

Example

Request

{
    "merchant_id": "Test-Integration-Merchant",
    "application_key": "Sandbox",
    "transaction_type": "sale",
    "currency": "EUR",
    "amount": 100,
    "card_data": {
        "card_number": "ZMq4wDaiaQ/xOwMEcQ7R3ASjTnoOMu+avLuJYgAnz1Q=",
        "card_exp": "WI8V4bE5/l8fIhUv6aMO8w==",
        "cvv": "BCm5yhYeeYoJlsOSIRd8Mg=="
    },
    "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
    },
    "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",
        "profile": 1
    },
    "mit": {
        "type": "initial",
        "expiry": 365
    },
    "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,
        "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,
        "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_incided": 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
}

Overview

Processing

Direct API

HPF API

Cashier API

Agent API

Subscription API

Objects

Webhooks

Demo

Migration to API 1.3

Direct API `{card}`

Endpoints

Request Parameters

Response Parameters

Signature

Example

Request

Response (3D Secure)

Response (Approved)

Response (Rejected)

Overview

Processing

Direct API

HPF API

Cashier API

Agent API

Subscription API

Objects

Webhooks

Demo

Migration to API 1.3

Direct API {card}

Endpoints

Request Parameters

Response Parameters

Signature

Example

Request

Response (3D Secure)

Response (Approved)

Response (Rejected)

Direct API `{card}`