Praxis Wiki logo

Direct API {direct} Sale

Sale transaction method over Direct API lets you accept the payments via local e-wallet and online banking solutions with an easy one-time integration.

{danger.fa-exclamation} IMPORTANT #1: Sometimes transaction_id (PSP transaction identifier) is empty, this may happen in the cases when the PSP has rejected the processing attempt due to input validation or unavailability of the processing gateway.

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


Name URL


Variable Type Description
amount int(20) Required. 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
currency varchar(10) Required. Transaction currency
pin varchar(50) Required. Unique customer id in your system
country varchar(2) Required. ISO 3166-1 alpha-2 (US, MT, IT, GB, DE etc)
data_PARAM - Optional. List of zero-to-many parameters according to specification of each specific PSP. See Direct API Data Fields for more details.
gateway varchar(32) Required. Gateway doing the processing
application_key varchar(32) Required. Identifier of your application (website)
merchant_id varchar(50) Required. Merchant API client account identifier
return_url varchar(256) Required. User will be redirected to a specified URL upon 3D Secure confirmation (in case of 3D Secure flow)
notification_url varchar(256) Required. URL to which the deposit status notification will be sent
order_id varchar(50) Required. Transaction identifier in your system
transaction_type varchar(8) Required. Transaction type. Must be set to sale for deposit
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
timestamp int(11) Required. Request time. URL will be active during 1 min after this time
version varchar(3) Required. API version
signature varchar(96) Required. Request signature. Please refer to How to Build Signature for details on signing the request.


Variable Type Description
status int Required.
- 0 if the request was successful
- Negative integer if internal server/network error occurs
- Positive integer if application/logical error occurs
description varchar(256) Required. Accurate description of the result. Return the actual error for any exception as it helps to diagnose issues in production
redirect_url varchar(256) Optional. Redirect URL to login or payment page at PSP. Appears only in combination with "transaction_status":"pending_async"
trace_id int(11) Optional. Transaction identifier in
transaction_id varchar(50) Optional. Transaction identifier in PSP
transaction_status varchar(16) Required.
- pending - processing initiated, final response expected from PSP
- approved - processing was successful
- rejected - processing failed
- pending_async - customer action expected (3D Secure, etc.)
payment_processor varchar(25) Optional. Actual payment service provider
payment_method varchar(25) Optional. Payment method, whether it is predefined and corresponds to PSP or one of variety methods offered by PSP as a part of payment process
error_code int(10) Optional. Error code for rejected transactions
error_details varchar(256) Optional. Error description for rejected transactions
version varchar(3) Required. API version
signature varchar(96) Required. sha384 HASH code of response (same algorithm as request signature)


For example below: Merchant Secret = "MerchantSecretKey"

In this example we assume that our PSP requires full name as a part of request, accepted with data_full_name request attribute.


curl -X POST \ \
-H 'Content-Type: application/json' \
-d '{
    "amount": "100",
    "application_key": "Sandbox",
    "country": "GB",
    "currency": "USD",
    "data_full_name": "John Doe",
    "gateway": "s-pTSZyK23E1Ee5KZpcNbX_aFl0HuhQ0",
    "merchant_id": "Test-Integration-Merchant",
    "notification_url": "https:\/\/\/v1\/deposits\/tx-1560610955",
    "order_id": "test-1560610955",
    "pin": "1",
    "return_url": "https:\/\/\/payment_result\/tx-1560610955",
    "timestamp": 1588796654,
    "transaction_type": "sale",
    "version": "1.2",
    "signature": "cd2a4fac3deb0082f2faf414fa4723e9511c1b7c0f4d3e3fa724b1466b40a13ba4d148022a35a451a88079d2945f1611"

Response (Redirect)

    "description": "Ok",
    "error_code": "0",
    "error_details": "[TEST] Transaction status: redirect",
    "payment_processor": "Test E-Wallet",
    "redirect_url": "https:\/\/\/site\/process\/WEYrdE5XKzhhKzRjQjBIbE5kWlpLZz09",
    "status": 0,
    "trace_id": 1000000680,
    "transaction_id": "15607165967613",
    "transaction_status": "pending_async",
    "version": "1.2",
    "signature": "75d2fd31757ac3717c594983cec015130123f813979d6ffa74c096f506cad4587a774445836070014fbae2b109378596"

Response (Approved)

    "description": "Ok",
    "error_code": "0",
    "error_details": "[TEST] Transaction status: approved",
    "payment_processor": "Test E-Wallet",
    "redirect_url": null,
    "status": 0,
    "trace_id": 1000000681,
    "transaction_id": "15607165967620",
    "transaction_status": "approved",
    "version": "1.2",
    "signature": "6b3868298fda3b8ac824de0524db0dcd3ab6e2fb8c7234e091d10adb736dc7696faee249707e3ed41b566be585f087c6"

Response (Rejected)

    "description": "Ok",
    "error_code": "1",
    "error_details": "[TEST] Transaction status: rejected",
    "payment_processor": "Test E-Wallet",
    "redirect_url": null,
    "status": 0,
    "trace_id": 1000000682,
    "transaction_id": "15607165967622",
    "transaction_status": "rejected",
    "version": "1.2",
    "signature": "dfe57cca17865e091054c6240b36895d3c8b31efca081960e797b7b3c821811210a6f02a3932a25bca21e3f970594b97"

You are currently viewing version 3.4 Latest version here