Praxis Wiki logo

Direct API {refund}


{refund} API function allows you to refund an approved deposit transaction.
The refund is processed as a new transaction sent to the same PSP used for the original deposit, returning the amount back to the customer's account.

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


{danger.fa-exclamation} IMPORTANT 2: Ensure that the PSP supports the refund transaction type. If the refund amount differs from the original deposit amount, confirm that the PSP supports partial refunds.


{danger.fa-exclamation} IMPORTANT 3: Whether issuing a refund via Atlas or Direct API, the refund transaction currency must match the processing currency of the original deposit being refunded.


{danger.fa-exclamation} IMPORTANT 4: Direct API's refund functionality does not require PCI certification. Since no card data is transmitted through this resource, there are no associated PCI compliance requirements.

We use CryptoCompare for cryptocurrency rates, and Open Exchange Rates for FIAT currency exchange rates.
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/refund
Live https://gw.praxisgate.com/direct/refund

Request Parameters

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

Variable Type 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 refund.
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.
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.
order_id varchar(50) Transaction identifier in your system.
reference_id int(11) This value specifies the ID of deposit transaction to be refunded.
withdrawal_request_id int(11) ? 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.
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.
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. reference_id
  10. withdrawal_request_id

Response signature parameters

  1. status
  2. timestamp
  3. customer.customer_token
  4. transaction.tid
  5. transaction.transaction_status
  6. transaction.processed_currency
  7. transaction.processed_amount

Example

Request

{
    "application_key": "Sandbox",
    "merchant_id": "Test-Integration-Merchant",
    "transaction_type": "refund",
    "currency": "EUR",
    "cid": "3221",
    "amount": 100,
    "locale": "en-GB",
    "order_id": "test-1560610955",
    "reference_id": 756850,
    "withdrawal_request_id": 756853,
    "variable1": "your variable",
    "variable2": "if that is not enough, you can pass even one more variable",
    "variable3": null,
    "version": "1.3",
    "timestamp": 1590613956
}

Response (Approved)

{
    "status": 0,
    "description": "Ok",
    "customer": {
        "customer_token": "87cfb23a8f1e68e162c276b754d9c061",
        "country": "GB",
        "first_name": "John",
        "last_name": "Johnson",
        "avs_alert": 0,
        "verification_alert": null
    },
    "session": {
        "auth_token": "8a7sd87a8sd778ac961062c6bedddb8",
        "intent": "withdrawal",
        "session_status": "created",
        "order_id": "test-1560610955",
        "currency": "EUR",
        "amount": 100,
        "conversion_rate": 1.0,
        "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": "refund",
        "transaction_status": "approved",
        "tid": 756853,
        "transaction_id": "13397",
        "currency": "EUR",
        "amount": 100,
        "conversion_rate": 1.0,
        "processed_currency": "EUR",
        "processed_amount": 100,
        "fee": 0,
        "fee_included": 0,
        "fee_type": "flat",
        "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"
        },
        "wallet": null,
        "is_async": 0,
        "is_cascade": 0,
        "cascade_level": 0,
        "reference_id": 756850,
        "withdrawal_request_id": 756853,
        "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",
    "customer": {
        "customer_token": "87cfb23a8f1e68e162c276b754d9c061",
        "country": "GB",
        "first_name": "John",
        "last_name": "Johnson",
        "avs_alert": 0,
        "verification_alert": null
    },
    "session": {
        "auth_token": "8a7sd87a8sd778ac961062c6bedddb8",
        "intent": "withdrawal",
        "session_status": "created",
        "order_id": "test-1560610955",
        "currency": "EUR",
        "amount": 100,
        "conversion_rate": 1.0,
        "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": "refund",
        "transaction_status": "rejected",
        "tid": 756853,
        "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": "Credit Card",
        "payment_processor": "TestCardProcessor",
        "gateway": "s-pTSZyK23E1Ee5KZpcNbX_aFl0HuhQ0",
        "card": null,
        "wallet": null,
        "is_async": 0,
        "is_cascade": 0,
        "cascade_level": 0,
        "reference_id": 756850,
        "withdrawal_request_id": 756853,
        "account_identifier": null,
        "created_by": "INTERNET",
        "edited_by": "INTERNET",
        "status_code": "GE-001",
        "status_details": "Do not honor"
    },
    "version": "1.3",
    "timestamp": 1590611635
}