cancelDeal

Overview

The cancelDeal command cancels a payment transaction that has not yet been transmitted to Shva (Israel's payment processor). This operation can only be performed on transactions that remain in "Approved, pending transmission" status.

Unlike refunds, cancellations must be for the full transaction amount and can only be performed before the daily transmission to Shva (typically occurring around 11:00 PM). Once transmitted, you must use refundDeal instead.

Best Practice: In most cases, use refundDeal instead of cancelDeal. The refundDeal command automatically determines whether to cancel or refund based on transmission status.

Use cases

Cancel pre-transmission transactions: Cancel transactions before Shva transmission (typically before 11:00 PM daily cutoff)
Two-phase commit cancellations: Cancel approval (J5) requests in two-phase commits
Full-amount reversals: Only full transaction amounts can be cancelled (partial cancellations not supported)
Payment page cancellations: Handle cancellations from payment page integration

Request structure

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

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

Server Endpoints: Use the server endpoint provided during merchant onboarding (e.g., https://your-hyp-environment-url/xpo/Relay).

XML payload structure

<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <requestId/>
        <command>cancelDeal</command>
        <cancelDeal>
            <!-- At least one of the following required: tranId, cgUid, or orgUid -->
            <tranId>{transactionId}</tranId>
            <!-- OR <cgUid>{cgIdentifier}</cgUid> -->
            <!-- OR <ashraitEmvData><orgUid>{originalUid}</orgUid></ashraitEmvData> -->
            
            <!-- Optional parameters -->
            <terminalNumber>{terminalNumber}</terminalNumber>
        </cancelDeal>
    </request>
</ashrait>

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: 118374610

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 (e.g., original charge and refunds)

Example: 118374610

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: Shva-assigned transaction ID

Example:

<ashraitEmvData>
    <orgUid>25062617340908828192261</orgUid>
</ashraitEmvData>

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

authNumber - Authorization Number

Type: String Required: No Description: Authorization number from credit card company

Example: 7823673

Usage Notes:

Can be included for additional validation
Helps ensure correct transaction matching
From the original transaction response

user - User Field

Type: String 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
Free-text field for merchant use

cardId - Card ID

Type: String Required: No Description: Card identifier (requires cardExpiration)

Example: 1092880571131111

Usage Notes:

Must be used together with cardExpiration
Provides additional transaction validation
From tokenization or original transaction

cardExpiration - Card Expiration

Type: String (MMYY format) Required: No (required when using cardId) Description: Card expiration date

Example: 0629

Usage Notes:

Required when cardId is provided
Format must be MMYY
Must match card's actual expiration

shiftId1, shiftId2, shiftId3 - Shift identifiers for transaction grouping

Type: String Required: No Description: Optional shift identifiers for transaction organization and reporting

Usage Notes:

Used for internal transaction grouping
Helpful for reconciliation and reporting
Must match the original transaction if provided

shiftTxnDate - Shift transaction date

Type: String Required: No Description: Date associated with shift for transaction grouping

Usage Notes:

Used alongside shift ID parameters
Helps locate transactions within specific time periods

transactionCode - Transaction processing code

Type: String Required: No Description: Specific transaction code for processing context

Usage Notes:

Usually inherits from the original transaction
Used for specialized transaction handling

Response structure

Successful response

A successful cancelDeal response contains transaction details and confirmation of cancellation:

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>cancelDeal</command>
        <dateTime>2025-06-26 20:20</dateTime>
        <requestId/>
        <tranId>118374656</tranId>
        <result>000</result>
        <message>Permitted transaction</message>
        <userMessage>Permitted transaction</userMessage>
        <version>2000</version>
        <language>ENG</language>
        <cancelDeal>
            <status>000</status>
            <statusText>Permitted transaction</statusText>
            <terminalNumber>0882819014</terminalNumber>
            <transactionType code="52">Cancel</transactionType>
            <total>36500</total>
            <cgUid>118374610</cgUid>
            <!-- Additional transaction details -->
        </cancelDeal>
    </response>
</ashrait>

Key Response Fields:

result: 000 indicates successful cancellation
tranId: New transaction ID for the cancellation
transactionType: Shows Cancel (code 52)
total: Amount that was cancelled
cgUid: Links 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:

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>cancelDeal</command>
        <dateTime>2025-08-20 10:27</dateTime>
        <requestId />
        <tranId>119576367</tranId>
        <result>312</result>
        <message>There is no transaction found for canceling</message>
        <userMessage>There is no transaction found for canceling</userMessage>
        <additionalInfo />
        <version>2000</version>
        <language>Eng</language>
        <cancelDeal>
            <status>312</status>
            <statusText>There is no transaction found for canceling</statusText>
            <extendedStatus />
            <extendedStatusText />
            <extendedUserMessage />
            <terminalNumber>0882814011</terminalNumber>
            <cardBin />
            <cardMask />
            <cardLength>0</cardLength>
            <cardNo />
            <cardName />
            <cardExpiration />
            <cardType code="" />
            <extendedCardType code="" />
            <creditCompany code="" />
            <cardBrand code="" />
            <cardAcquirer code="" />
            <serviceCode />
            <transactionType code="" />
            <creditType code="" />
            <currency code="" />
            <baseCurrency />
            <baseAmount />
            <transactionCode code="" />
            <total />
            <firstPayment />
            <periodicalPayment />
            <numberOfPayments />
            <clubId />
            <validation code="" />
            <idStatus code="" />
            <cvvStatus code="" />
            <authSource code="" />
            <authNumber />
            <fileNumber />
            <slaveTerminalNumber />
            <slaveTerminalSequence />
            <eci />
            <clientIp />
            <email />
            <cavv code="" />
            <user />
            <addonData />
            <supplierNumber />
            <id />
            <shiftId1 />
            <shiftId2 />
            <shiftId3 />
            <shiftTxnDate />
            <cgUid />
            <cardHash />
            <ashraitEmvData>
                <mti>100</mti>
            </ashraitEmvData>
            <extendedTranCode />
            <sendNotification />
        </cancelDeal>
    </response>
</ashrait>

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

Code examples

#!/bin/bash

# Example 1: Cancel using tranId
curl -X POST https://your-hyp-environment-url/xpo/Relay \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "user=your_username" \
  -d "password=your_password" \
  -d "int_in=$(cat <<'EOF'
<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <requestId/>
        <command>cancelDeal</command>
        <cancelDeal>
            <tranId>118374610</tranId>
        </cancelDeal>
    </request>
</ashrait>
EOF
)"

# Example 2: Cancel using cgUid with optional terminalNumber
curl -X POST https://your-hyp-environment-url/xpo/Relay \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "user=your_username" \
  -d "password=your_password" \
  -d "int_in=$(cat <<'EOF'
<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <requestId/>
        <command>cancelDeal</command>
        <cancelDeal>
            <cgUid>118374610</cgUid>
            <terminalNumber>0882819014</terminalNumber>
        </cancelDeal>
    </request>
</ashrait>
EOF
)"

import java.io.*;
import java.net.*;
import java.nio.charset.StandardCharsets;

public class CancelDealExample {
    public static void main(String[] args) throws IOException {
        String serverUrl = "https://your-hyp-environment-url/xpo/Relay";
        String username = "your_username";
        String password = "your_password";
        
        String xmlPayload = 
            "<ashrait>" +
                "<request>" +
                    "<version>2000</version>" +
                    "<language>Eng</language>" +
                    "<dateTime/>" +
                    "<requestId/>" +
                    "<command>cancelDeal</command>" +
                    "<cancelDeal>" +
                        "<terminalNumber>0882819014</terminalNumber>" +
                        "<cgUid>118374610</cgUid>" +
                    "</cancelDeal>" +
                "</request>" +
            "</ashrait>";
        
        // Build POST data
        String postData = "user=" + URLEncoder.encode(username, StandardCharsets.UTF_8) +
                         "&password=" + URLEncoder.encode(password, StandardCharsets.UTF_8) +
                         "&int_in=" + URLEncoder.encode(xmlPayload, StandardCharsets.UTF_8);
        
        // Send request
        URL url = new URL(serverUrl);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("POST");
        connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
        connection.setDoOutput(true);
        
        try (OutputStream os = connection.getOutputStream()) {
            os.write(postData.getBytes(StandardCharsets.UTF_8));
        }
        
        // Read response
        try (BufferedReader reader = new BufferedReader(
                new InputStreamReader(connection.getInputStream()))) {
            String line;
            StringBuilder response = new StringBuilder();
            while ((line = reader.readLine()) != null) {
                response.append(line);
            }
            System.out.println(response.toString());
        }
    }
}

import requests
from urllib.parse import urlencode

def cancel_deal(terminal_number, cg_uid):
    """Cancel a transaction using CG identifier"""
    
    server_url = "https://your-hyp-environment-url/xpo/Relay"
    username = "your_username"
    password = "your_password"
    
    xml_payload = f"""
    <ashrait>
        <request>
            <version>2000</version>
            <language>ENG</language>
                <requestId/>
            <command>cancelDeal</command>
            <cancelDeal>
                <terminalNumber>{terminal_number}</terminalNumber>
                <cgUid>{cg_uid}</cgUid>
            </cancelDeal>
        </request>
    </ashrait>
    """
    
    # Prepare POST data
    post_data = {
        'user': username,
        'password': password,
        'int_in': xml_payload.strip()
    }
    
    try:
        # Send request
        response = requests.post(
            server_url,
            data=post_data,
            headers={'Content-Type': 'application/x-www-form-urlencoded'},
            timeout=30
        )
        
        response.raise_for_status()
        return response.text
        
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None

# Example usage
if __name__ == "__main__":
    result = cancel_deal("0882819014", "118374610")
    if result:
        print("Cancellation response:")
        print(result)

const https = require('https');
const querystring = require('querystring');

function cancelDeal(terminalNumber, cgUid) {
    return new Promise((resolve, reject) => {
        const serverUrl = 'https://your-hyp-environment-url/xpo/Relay';
        const username = 'your_username';
        const password = 'your_password';
        
        const xmlPayload = `
        <ashrait>
            <request>
                <version>2000</version>
                <language>ENG</language>
                        <requestId/>
                <command>cancelDeal</command>
                <cancelDeal>
                    <terminalNumber>${terminalNumber}</terminalNumber>
                    <cgUid>${cgUid}</cgUid>
                </cancelDeal>
            </request>
        </ashrait>
        `;
        
        // Prepare POST data
        const postData = querystring.stringify({
            user: username,
            password: password,
            int_in: xmlPayload.trim()
        });
        
        const options = {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
                'Content-Length': Buffer.byteLength(postData)
            }
        };
        
        const req = https.request(serverUrl, options, (res) => {
            let responseData = '';
            
            res.on('data', (chunk) => {
                responseData += chunk;
            });
            
            res.on('end', () => {
                if (res.statusCode === 200) {
                    resolve(responseData);
                } else {
                    reject(new Error(`HTTP ${res.statusCode}: ${responseData}`));
                }
            });
        });
        
        req.on('error', (error) => {
            reject(error);
        });
        
        req.write(postData);
        req.end();
    });
}

// Example usage
async function example() {
    try {
        const result = await cancelDeal('0882819014', '118374610');
        console.log('Cancellation response:');
        console.log(result);
    } catch (error) {
        console.error('Cancellation failed:', error.message);
    }
}

example();

Error codes

Error Code

Description

Resolution

310

No debit deal matches the credit deal

Verify lookup parameters match an existing transaction

312

No transaction found for canceling

Check transaction ID and lookup criteria

313

Transaction has already been transmitted

Use refundDeal instead for transmitted transactions

314

Transaction has already been canceled

Transaction was previously cancelled successfully

317

Missing required parameters

Ensure at least one lookup element is provided

319

Terminal not permitted to cancel

Contact support to enable cancellation permissions

320

Credit transaction already performed

Cannot cancel transactions that already have credits

332

Multiple transactions found

Use more specific lookup criteria or enable "Block multiple matches" terminal setting

refundDeal - Refund transmitted transactions (automatically falls back to cancel when appropriate)
doDeal - Process initial payment transactions
Request Structure - General API request format
Refunds & Cancellations - Detailed guide on when to use each operation

PreviousaddCgInvoice NextdoDeal

Last updated 3 months ago

Was this helpful?

Good afternoon

Overview

Use cases

Request structure

XML payload structure

Required parameters

Optional parameters

Response structure

Successful response

Error response

Code examples

Error codes

Related commands