Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

refundDeal

Overview

The refundDeal command refunds funds to customers for transactions that have already been settled. This command automatically handles the complexity of refund vs cancellation logic based on the transaction's transmission status to Shva (Israel's payment processor).

Key Features:

  • Automatic fallback: Cancels non-transmitted transactions, refunds transmitted ones

  • Partial refunds: Support for amounts less than the original transaction

  • Installment flexibility: Customizable refund schedules for installment transactions

  • Multiple lookup methods: Find transactions using various identifiers

Best Practice: Use refundDeal instead of cancelDeal when unsure about transmission status. The system automatically determines whether to cancel or refund based on the transaction state.

Use cases

  • Refund settled transactions: Process refunds for transactions that have been transmitted to Shva (see Refunds & Cancellations)

  • Partial refunds: Support for amounts less than the original transaction with flexible refund scheduling

  • Customer refund requests: Handle standard customer refund scenarios (recommended over cancelDeal in most cases)

  • Installment transaction refunds: Refund installment transactions with customizable refund schedules (see Refunds & Cancellations)

  • Automatic fallback processing: Let the system determine whether to cancel or refund based on transmission status

  • Invoice-specific refunds: Use with refundCgInvoice for document-tied refunds

Request structure

For a comprehensive overview of the API request format and authentication, see API Request & Response General Structure.

Send a standard Hyp Enterprise API request to your assigned server endpoint with the refundDeal command in the int_in parameter.

The refundDeal command uses the following endpoint:

POST https://your-hyp-environment-url/xpo/Relay

Request parameters

Parameter
Type
Description

user

string

Username for API authentication (body parameter)

password

string

Password for API authentication (body parameter)

int_in

string

XML payload containing the request data (body parameter)

XML payload structure

Required parameters

At least one of the following three parameters must be provided:

tranId - Transaction ID

Type: String Required: At least one lookup parameter required Description: Unique transaction request ID for a specific transaction step

Example: 118372223

Usage Notes:

  • When provided, other lookup elements are ignored

  • Most specific identifier for a transaction step

  • Returned in response from the original transaction

cgUid - CG Identifier

Type: String Required: At least one lookup parameter required Description: CG identifier shared across related transactions (finds latest transaction state)

Example: 118372223

Usage Notes:

  • Links related transactions together

  • Useful for tracking transaction chains

  • Returned in response from the original transaction

orgUid - Original UID

Type: String Required: At least one lookup parameter required Description: A unique transaction ID assigned according to the Ashrait protocol

Example:

Usage Notes:

  • Must be wrapped in ashraitEmvData element

  • Unique identifier from Shva payment processor

  • Used for direct transaction reference

Optional parameters

terminalNumber - Your merchant terminal identifier

Type: String Required: No Description: The unique terminal number assigned during merchant onboarding

Example: 0882819014

Usage Notes:

  • Must match your assigned terminal number

  • Used for transaction lookup and authorization

  • Available in your merchant dashboard

user - User Field

Type: String (1-19) Required: No Description: Custom user identifier from original transaction

Example: customer123

Usage Notes:

  • Must match the value from the original transaction

  • Useful for merchant-specific tracking

total - Refund amount in currency subunits

Type: String (numeric) Required: No Description: Amount to refund in cents/agorot (e.g., 4730 = $47.30)

Default: Full amount of original transaction Example: 4730 (refunds $47.30)

Usage Notes:

  • Must be less than or equal to the original transaction amount

  • For partial refunds, the original transaction remains unchanged

  • Even partial refunds of non-transmitted transactions create credit transactions

creditType - Credit type for installment refunds

Type: String Required: No Description: Specifies the credit type if the refund is for a transaction that involved installments.

Valid Values: Payments (regular installments), SpecialCredit (credit installments)

Example: Payments

firstPayment - Amount of the first installment

Type: Numeric Required: No Description: The amount of the first installment in currency subunits such as cents or agorot.

Example: 1000

Usage Notes:

  • Only used if the original transaction was an installment transaction

  • When refunding an installment transaction, the total refund amount must equal firstPayment plus periodicalPayment multiplied by numberOfPayments

periodicalPayment - Amount of subsequent installments

Type: Numeric Required: No Description: The amount of each subsequent installment in currency subunits such as cents or agorot.

Example: 1000

Usage Notes:

  • Only used if the original transaction was an installment transaction

numberOfPayments - Number of payments in the refund

Type: Numeric Required: No Description: The number of payments in the refund transaction.

Example: 1

Usage Notes:

  • Overrides the default behavior of mirroring the original transaction's payment schedule

  • If you set this to a specific value, you must also provide a valid explicit breakdown using firstPayment and periodicalPayment

  • The breakdown is subject to validation against the original transaction structure; if it doesn't match, the request may be rejected

  • To reliably issue a single-installment refund for any amount without providing a manual breakdown, use allowOnePayment instead

allowOnePayment - Allow single payment refund

Type: Numeric (0 or 1) Required: No Description: When set to 1, allows performing a refund for any amount in a single installment, overriding the "Allow installment refund" terminal setting. Use this parameter for a reliable single-installment refund when no manual breakdown is provided.

Valid Values: 0 (default), 1 Example: 1

Usage Notes:

  • Only applies to transactions where creditType is set to Payments

  • Only applies when neither firstPayment nor periodicalPayment is included in the refund request

  • This overrides the system restriction that normally prevents single-installment refunds unless the transaction total divided by the number of installments is less than 1. The merchant takes responsibility for the risk management logic.

shiftId1, shiftId2, shiftId3 - Shift identifiers for transaction grouping

Type: String Required: No Description: Used to mark the refund transaction with shift values

Usage Notes:

  • Used for internal transaction grouping

  • Helpful for reconciliation and reporting

  • Not suitable for searching the original debit transaction

Response structure

Successful response

A successful refundDeal response contains details of the new credit transaction:

Key Response Fields:

  • result: 000 indicates successful refund

  • tranId: New transaction ID for the refund/cancellation

  • transactionType: Shows transaction type (Cancel for non-transmitted, Refund for transmitted)

  • total: Amount that was refunded

  • cgUid: Links back to original transaction

Error response

Error responses include specific error codes and messages. The response contains many fields, most of which will be empty for error cases. The key fields to focus on are result, message, userMessage, status, and statusText:

Note: Error responses include the full structure with many empty fields. Focus on the result, status, and message fields for error handling.

Code examples

Error codes

Error Code
Description
Resolution

310

No debit deal matches the credit deal

Verify lookup parameters match an existing transaction

317

Missing required parameters

Ensure at least one lookup element is provided

320

Credit transaction already performed

Transaction already has a refund; cannot refund again

321

Credit amount differs from charge deal amount

Check refund amount against original transaction

324

Terminal not permitted to perform refund transactions

Contact support to enable refund permissions

332

Multiple transactions found

Use more specific lookup criteria or configure terminal settings

339

Refund credit type differs from original transaction

Ensure creditType matches original transaction

340

Refund number of payments differs from original transaction

Verify installment configuration

341

Refund amount differs from original transaction

Check amount validation settings

  • doDeal - Process original payment transactions that can later be refunded

  • cancelDeal - Cancel non-transmitted transactions (refundDeal automatically chooses this when appropriate)

  • inquireTransactions - Check transaction status and transmission state before refunding

  • refundCgInvoice - Process invoice-specific refunds with document generation

  • Request Structure - General API request format

  • Refunds & Cancellations - Detailed guide on refund vs cancellation logic and installment handling

Last updated

Was this helpful?