Praxis Wiki logo

Direct API {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} 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.

Endpoints

Name URL
Sandbox https://gateway.cashier-test.com/direct/refund
Live https://gateway.praxispay.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.
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
cid varchar(50) Unique customer id in your system
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 transaction to be refunded
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
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.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": "refund",
        "transaction_status": "approved",
        "tid": 756853,
        "transaction_id": "13397",
        "currency": "EUR",
        "amount": 100,
        "conversion_rate": 1.000000,
        "processed_currency": "EUR",
        "processed_amount": 100,
        "fee": 0,
        "fee_incided": 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.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": "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_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": 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
}