Cheat Sheet: Using Query API with OCT Timeout Scenario

Visa Employee



  1. How to specify timeout duration for VD Push Funds Transaction API (OCT)
    • We are going to run PUSH (OCT)
    • Simulate Timeout for PUSH(OCT) transaction by passing header “x-transaction-timeout-ms","1"
    • Note: The value of x-transaction-timeout-ms is in milliseconds. For example, to set timeout of 10 seconds, the value of x-transaction-timeout-ms should be 10000.
  1. How to use Query API to check status of an OCT Transaction
    • We are going to invoke the Query API using retrievalReferenceNumber and systemsTraceAuditNumber to retrieve the OCT transaction status
    • The same can be used to retrieve status of a timed out OCT transaction as well


  1. If Query API was not able to retrieve the transaction, we would have to use retry logic and resend the PUSH (OCT) transaction again, with same field values for







Links for the previous webinars:



For the How to Run the Query API in Visa Direct Transactions webinar:


  1. Preparation for invoking OCT transaction:

We have to capture correlation_id for logging purpose




correlation_id = response.headers.get("X-CORRELATION-ID")

print("correlation_id", correlation_id)


We need to generate





number , 6 characters

A unique value should be used for each API method. However, when passing the (AFTR) method, this value must match the systemsTraceAuditNumber previously passed with the AFT method for the current transaction.




number , 12 characters

A value used to tie together service calls related to a single financial transaction. When passing Account Funding Transaction (AFT) and an Original Credit Transaction (OCT) methods, this value must differ between the two methods. When passing the Account Funding Transaction Reversal (AFTR) method, this value must match the retrievalReferenceNumber previously passed with the AFT method for this transaction.

Recommended Format : ydddhhnnnnnn

The first fours digits must be a valid yddd date in the Julian date format, where the first digit = 0-9 (last digit of current year) and the next three digits = 001-366 (number of the day in the year). hh can be the two digit hour in a 24 hour clock (00-23) during which the transaction is performed.
nnnnnn can be the systemsTraceAuditNumber or any 6 digit number.


Now to simulate a timeout for the OCT transaction. We have to add header

“x-transaction-timeout-ms","1" (it is case insensitive)


headers = { "content-type": "application/json",

            "Accept": "application/json",

            "X-Transaction-Timeout-MS" : "1"



  1. Now invoke the OCT transaction with timeout header by following the steps elaborated above


  1. Now we are ready for Query API


Query API


Use case:

Now we would like to use Query API to retrieve results from the Push (OCT) transaction.



The Query API allows service providers to query in real-time the processing status of Visa Direct (Account Funding and Original Credit) transactions as well as other related transactions that are part of the Visa Direct suite of transactions (Reversals, Adjustments, Chargebacks and Re-presentments).


It allows service providers to query history of transactions and return the entire transaction set related to the original Visa Direct transaction. A transaction set will include approved and settled original Visa Direct transactions, reversals, chargebacks, adjustments, and re-presentments. 


  1. Now we can use below to invoke Query API

stan and rrn parameters combination


url = '' + str(acquiringBin) + '&stan=' + str(systemsTraceAuditNumber) + '&rrn=' + str(retrievalReferenceNumber)