Praxis Wiki logo

Direct API {direct} Refund

{refund} API function lets you refund the approved deposit transaction. The refund will be a new transaction sent to the same PSP as the one used for the original deposit transaction in order to send the same amount back to customer's account.

{danger.fa-exclamation} IMPORTANT #1: The original referenced transaction (see reference_id request parameter) has to be a deposit having the approved status.

{danger.fa-exclamation-triangle} IMPORTANT #2: Please make sure that the PSP supports the refund transaction type. If the refund amount is different from the original deposit amount, you will also need to confirm that the PSP supports the partial refunds.


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 refund
profile int(2) Optional. Customer's profile level. Different profile levels may be used to configure the transaction and payment method limits
reference_id int(11) Required. This value specifies the ID of transaction to be refunded
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": "200",
    "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": "refund",
    "reference_id": "3145511",
    "version": "1.2",
    "signature": "d2dk31aoqi2urutf2faf414fa4723e9511c1b7c0f4d3e3fa724b1466b40a13ba4d148022a35a451a88079d2945f1611"

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: refund",
    "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