Direct API {apm}

---

• ENDPOINTS
• CHECKLIST
• REQUEST PARAMETERS
• RESPONSE PARAMETERS
• SIGNATURE
• EXAMPLE

Direct API lets you use a single integration to connect with a variety of e-wallets and online banking solutions. In few easy steps you will open a direct path for your customers to pay in most convenient way with their local payment solutions.

Currently Direct API offers the following APIs:
- {sale} lets you receive the card payments from customers;
- {payout} is a fund transfer from your merchant account to customer's wallet or bank account;

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;

Direct API is a single integration to let your customers pay with a number of alternative payment methods directly. For that reason the API call for each payment method is slightly different: it has to consider the local personal ID or e-wallet payer identity, whichever is being used by a certain payment solution.

{danger.fa-exclamation-triangle} IMPORTANT #1: Some APM solutions do not accept some or any customer and payment details over API, meaning that the customer will be requested to enter the details at the APM's transaction details page.

---

{danger.fa-exclamation} IMPORTANT #2: 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	https://gateway.cashier-test.com/direct/apm
Live	https://gw.praxisgate.com/direct/apm

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)
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
wallet_data	<Object>	✓	✓	✓	Wallet data object
cid	varchar(50)	✓	✓	✓	Unique customer id in your system
locale	varchar(5)	✓	✓	✓	User locale. See locales reference for the full list of supported locales
gateway	varchar(32)	✓	✓	✓	APM 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 trace_id 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

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

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_data": {
        "full_name": "John Johnson",
        "bank_account": "11112222333344",
        "bank_name": "Random Bank, London",
        "bank_code": "AABBCC",
        "iban": "GB999911112222333344"
    },
    "cid": "1",
    "locale": "en-GB",
    "gateway": "XkI4sCxOBpcXylpK3-7ycM39RLTAqsyt",
    "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 (Async)

{
    "status": 0,
    "description": "Ok",
    "redirect_url": "https:\/\/compute.praxispay.com\/login\/8a7sd87a8sd778ac961062c6bedddb8",
    "customer": {
        "customer_token": "87cfb23a8f1e68e162c276b754d9c061",
        "country": null,
        "first_name": null,
        "last_name": null,
        "avs_alert": null,
        "verification_alert": null
    },
    "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
    },
    "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_incided": 0,
        "fee_type": "flat",
        "payment_method": "WireOnline",
        "payment_processor": "TestWallet",
        "gateway": "XkI4sCxOBpcXylpK3-7ycM39RLTAqsyt",
        "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_3d": 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-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": null,
        "first_name": null,
        "last_name": null,
        "avs_alert": null,
        "verification_alert": null
    },
    "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
    },
    "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": "WireOnline",
        "payment_processor": "TestWallet",
        "gateway": "XkI4sCxOBpcXylpK3-7ycM39RLTAqsyt",
        "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_3d": 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": null,
        "first_name": null,
        "last_name": null,
        "avs_alert": null,
        "verification_alert": null
    },
    "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
    },
    "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,
        "payment_method": "WireOnline",
        "payment_processor": "TestWallet",
        "gateway": "XkI4sCxOBpcXylpK3-7ycM39RLTAqsyt",
        "card": null,
        "wallet": null,
        "is_3d": 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,
    "signature": "64c181094246006b2c22d63cf9fa95e2cdfe5ba4d1c78a2c981448af5bffeaee627a3633891292a935290a7b804a06eb"
}