Direct API {refund}

---

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

{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
}