Get Single Transaction

Description: Retrieves detailed information about a single transaction by its ID or retrieval reference number. This endpoint is useful for looking up transaction details, checking status, or retrieving information for customer service inquiries.

Path Parameters

Authentication

This endpoint requires bearer token authentication using the Authorization header.

Code Examples

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

public class TransactionClient
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl = "https://your-api-domain.com";
    private readonly string _bearerToken;

    public TransactionClient(string bearerToken)
    {
        _bearerToken = bearerToken;
        _httpClient = new HttpClient();
        _httpClient.BaseAddress = new Uri(_baseUrl);
        _httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", _bearerToken);
        _httpClient.DefaultRequestHeaders.Accept.Add(
            new MediaTypeWithQualityHeaderValue("application/json"));
    }

    public async Task<string> GetTransactionAsync(
        string merchantId,
        string transactionId)
    {
        try
        {
            string endpoint = $"/v1/rest/merchants/{merchantId}/transactions/{transactionId}";

            HttpResponseMessage response = await _httpClient.GetAsync(endpoint);
            response.EnsureSuccessStatusCode();

            return await response.Content.ReadAsStringAsync();
        }
        catch (HttpRequestException e)
        {
            Console.WriteLine($"Request error: {e.Message}");
            throw;
        }
    }
}

// Example usage with transaction GUID
var client = new TransactionClient("your-bearer-token-here");
string transaction = await client.GetTransactionAsync(
    "12345678901",                              // merchantId
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"     // transactionId (GUID)
);
Console.WriteLine(transaction);

// Example usage with retref
string transaction2 = await client.GetTransactionAsync(
    "12345678901",      // merchantId
    "123456789"         // transactionId (retref)
);
Console.WriteLine(transaction2);

Imports System
Imports System.Net.Http
Imports System.Net.Http.Headers
Imports System.Threading.Tasks

Public Class TransactionClient
    Private ReadOnly _httpClient As HttpClient
    Private ReadOnly _baseUrl As String = "https://your-api-domain.com"
    Private ReadOnly _bearerToken As String

    Public Sub New(bearerToken As String)
        _bearerToken = bearerToken
        _httpClient = New HttpClient()
        _httpClient.BaseAddress = New Uri(_baseUrl)
        _httpClient.DefaultRequestHeaders.Authorization =
            New AuthenticationHeaderValue("Bearer", _bearerToken)
        _httpClient.DefaultRequestHeaders.Accept.Add(
            New MediaTypeWithQualityHeaderValue("application/json"))
    End Sub

    Public Async Function GetTransactionAsync(
        merchantId As String,
        transactionId As String) As Task(Of String)

        Try
            Dim endpoint As String = $"/v1/rest/merchants/{merchantId}/transactions/{transactionId}"

            Dim response As HttpResponseMessage = Await _httpClient.GetAsync(endpoint)
            response.EnsureSuccessStatusCode()

            Return Await response.Content.ReadAsStringAsync()
        Catch e As HttpRequestException
            Console.WriteLine($"Request error: {e.Message}")
            Throw
        End Try
    End Function
End Class

' Example usage
Dim client As New TransactionClient("your-bearer-token-here")
Dim transaction As String = Await client.GetTransactionAsync(
    "12345678901",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
)
Console.WriteLine(transaction)

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class TransactionClient {
    private final String baseUrl;
    private final String bearerToken;
    private final HttpClient httpClient;

    public TransactionClient(String baseUrl, String bearerToken) {
        this.baseUrl = baseUrl;
        this.bearerToken = bearerToken;
        this.httpClient = HttpClient.newHttpClient();
    }

    public String getTransaction(String merchantId, String transactionId)
            throws IOException, InterruptedException {

        String endpoint = baseUrl + "/v1/rest/merchants/" + merchantId +
                         "/transactions/" + transactionId;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(endpoint))
            .header("Authorization", "Bearer " + bearerToken)
            .header("Accept", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = httpClient.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        if (response.statusCode() != 200) {
            throw new IOException("HTTP Error: " + response.statusCode());
        }

        return response.body();
    }
}

// Example usage
TransactionClient client = new TransactionClient(
    "https://your-api-domain.com",
    "your-bearer-token-here"
);

String transaction = client.getTransaction(
    "12345678901",
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
);
System.out.println(transaction);

require 'net/http'
require 'uri'
require 'json'

class TransactionClient
  def initialize(base_url, bearer_token)
    @base_url = base_url
    @bearer_token = bearer_token
  end

  def get_transaction(merchant_id, transaction_id)
    endpoint = "#{@base_url}/v1/rest/merchants/#{merchant_id}/transactions/#{transaction_id}"
    uri = URI.parse(endpoint)

    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    request = Net::HTTP::Get.new(uri.request_uri)
    request['Authorization'] = "Bearer #{@bearer_token}"
    request['Accept'] = 'application/json'

    response = http.request(request)

    if response.code.to_i != 200
      raise "HTTP Error: #{response.code} - #{response.body}"
    end

    response.body
  end
end

# Example usage
client = TransactionClient.new(
  'https://your-api-domain.com',
  'your-bearer-token-here'
)

transaction = client.get_transaction(
  '12345678901',
  'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
)
puts transaction

Response Format

Success Response (HTTP 200) - Approved Transaction

{
  "responseStatus": "TransactionApproved",
  "responseMessage": "Approved",
  "responseCode": "000",
  "responseReason": null,
  "responseResult": "success",
  "legacyResponseCode": "A",
  "correlationId": "abc123-def456-ghi789",
  "customAttributes": {
    "invoiceNumber": "INV-001",
    "department": "Sales"
  },
  "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "retref": 123456789,
  "merchid": "12345678901",
  "locationid": 5,
  "transactionAmount": "150.00",
  "authAmount": "150.00",
  "cardExpiry": "1227",
  "accttype": "VISA",
  "maskedAccountNumber": "************1234",
  "lastfour": "1234",
  "abaRoutingNumber": null,
  "idLimitedBitFlag": true,
  "payorId": "5513027774438108364",
  "savedPaymentMethodId": "5513027774438108365",
  "accountHolderName": "John Doe",
  "address": "123 Main St",
  "city": "Springfield",
  "postal": "62701",
  "region": "IL",
  "phone": "555-1234",
  "email": "john.doe@example.com",
  "orderid": "ORD-2026-12345",
  "simulatedBatchId": "BATCH-2026-001",
  "transtype": "Ecomm",
  "transinit": "Consumer",
  "recurring": false,
  "allowPartial": true,
  "linkedTransactionId": null,
  "binInformation": {
    "binId": "dGVzdC1iaW4taWQ",
    "cardType": "Credit",
    "brandName": "Visa",
    "fundingSource": "Credit",
    "bin": "456789",
    "issuerInformation": {
      "name": "Example Bank",
      "country": "US",
      "phoneNumber": "1-800-555-0100"
    },
    "surcharge": "Allowed"
  },
  "fees": [],
  "surchargeCompliant": false,
  "allowDuplicateTransaction": false,
  "hostrespcode": "00",
  "authrespcode": "A",
  "avsCode": "Y",
  "retdecdate": null,
  "requestDate": "2026-04-02T10:30:00Z",
  "authDate": "2026-04-02T10:30:03Z",
  "settlementDate": "2026-04-03T03:00:00Z",
  "settlementStatus": "Accepted",
  "sponsorKey": null
}

Declined Transaction Response

{
  "responseStatus": "TransactionDeclined",
  "responseMessage": "Insufficient Funds",
  "responseCode": "051",
  "responseReason": "The transaction was declined due to insufficient funds",
  "responseResult": "failure",
  "legacyResponseCode": "D",
  "correlationId": "xyz789-abc123-def456",
  "transactionId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "retref": 123456790,
  "merchid": "12345678901",
  "locationid": 5,
  "transactionAmount": "150.00",
  "authAmount": "0.00",
  "accttype": "VISA",
  "maskedAccountNumber": "************5678",
  "lastfour": "5678",
  "accountHolderName": "Jane Smith",
  "orderid": "ORD-2026-12346",
  "requestDate": "2026-04-02T10:31:00Z",
  "retdecdate": "2026-04-02T10:31:03Z",
  "settlementStatus": "Declined",
  "hostrespcode": "51",
  "authrespcode": "D"
}

Response Fields

HTTP Status Codes

Understanding Settlement Status

Common Use Cases

1. Customer Service Inquiry

Customer calls asking about a charge on their statement:

// Look up transaction by retref (customer can read this from their statement)
string transaction = await client.GetTransactionAsync("12345678901", "123456789");

// Parse and display to customer service rep
var txn = JsonConvert.DeserializeObject<Transaction>(transaction);
Console.WriteLine($"Order: {txn.OrderId}");
Console.WriteLine($"Amount: ${txn.TransactionAmount}");
Console.WriteLine($"Date: {txn.AuthDate}");
Console.WriteLine($"Card: ending in {txn.LastFour}");

2. Verify Payment Before Shipping

Check that a transaction has settled before shipping an order:

string transaction = await client.GetTransactionAsync(merchantId, transactionId);
var txn = JsonConvert.DeserializeObject<Transaction>(transaction);

if (txn.SettlementStatus == "Accepted" || txn.SettlementStatus == "Authorized")
{
    Console.WriteLine("Safe to ship - payment confirmed");
    ShipOrder(txn.OrderId);
}
else
{
    Console.WriteLine("Do not ship - payment issue");
}

3. Generate Receipt

Get transaction details to display on a receipt:

string transaction = await client.GetTransactionAsync(merchantId, transactionId);
var txn = JsonConvert.DeserializeObject<Transaction>(transaction);

GenerateReceipt(new Receipt
{
    OrderNumber = txn.OrderId,
    Amount = txn.TransactionAmount,
    PaymentMethod = $"{txn.AcctType} ending in {txn.LastFour}",
    TransactionDate = txn.AuthDate,
    Status = txn.ResponseMessage
});

4. Check for Refunds

Determine if a transaction has been refunded:

string transaction = await client.GetTransactionAsync(merchantId, transactionId);
var txn = JsonConvert.DeserializeObject<Transaction>(transaction);

if (txn.SettlementStatus == "Refunded")
{
    Console.WriteLine("This transaction has been fully refunded");
}
else if (txn.SettlementStatus == "PartiallyRefunded")
{
    Console.WriteLine("This transaction has been partially refunded");
}

5. Reconciliation

Verify transactions match your order records:

// Get transaction from payment gateway
string transaction = await client.GetTransactionAsync(merchantId, transactionId);
var txn = JsonConvert.DeserializeObject<Transaction>(transaction);

// Compare with your order database
var order = await GetOrderFromDatabase(txn.OrderId);

if (order.Amount != decimal.Parse(txn.TransactionAmount))
{
    Console.WriteLine("WARNING: Amount mismatch!");
    LogReconciliationError(order, txn);
}

Best Practices

1. Store Both IDs

Always store both the transactionId (GUID) and retref (numeric) in your database. The GUID is more reliable for API calls, but the retref is easier for customer service to communicate.

2. Check Settlement Status

Don't assume a transaction is complete just because it was approved. Check the settlementStatus to know if funds have actually been transferred.

3. Handle 400 Errors Gracefully

A 400 error means the merchant doesn't own this transaction. This is a security feature to prevent merchants from accessing each other's transactions.

4. Use for Audit Trails

Periodically retrieve transactions to verify they match your records. This helps catch any discrepancies early and ensures your books are accurate.

5. Display Masked Numbers Only

Always use the maskedAccountNumber or lastfour when displaying payment information to users. Never display full account numbers.

Troubleshooting

Additional Notes

• You can use either the transaction GUID or the retref number as the transaction ID parameter
• Settlement dates may be null for very recent transactions that haven't settled yet
• The binInformation object contains detailed card information (for credit cards only)
• Custom attributes you provided during transaction creation are returned in the response
• Declined transactions are still stored and retrievable for audit purposes
• The linkedTransactionId field links refunds/voids to their original transaction
• ACH transactions may change status days after the initial authorization
• For privacy, full account numbers are never returned - only masked versions