Developer API - Transactions

  1. Transaction attributes
  2. List of all transactions
  3. Find transactions by status
  4. Find transactions by type
  5. Find transactions by serial number
  6. Find transactions by app name
  7. Find transactions by date
  8. Find transactions by multiple parameters
  9. Parsed transaction data

Transaction attributes

A transaction have the following attributes:

Name Type Description
id Integer Record ID
transaction_type String Record type: Release company, Transaction switch or Download get_asset
serial_number String Device serial number
logical_number String Device logical number
app_name String Application that originated the transaction
detail String Additional details about the transaction (might be empty)
framework_version String Framework version installed on the device
status String Record status: Success success, Processing running or Error fail
sent String Information sent to the host
received String Information received from the host
parsed Object Parsed transaction data (financial applications only)
started_at String Timestamp in ISO 8601 format
finished_at String Timestamp in ISO 8601 format

List of all transactions

Return an array with all transactions.

Method and URL format

GET https://api.cloudwalk.io/{version}/transactions?access_token={token}

Example of use

$ curl -X GET "https://api.cloudwalk.io/v1/transactions?access_token=$TOKEN"
require 'net/http'

token = 'API_TOKEN'

uri = URI("https://api.cloudwalk.io/v1/transactions?access_token=#{token}")

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

request = Net::HTTP::Get.new(uri.request_uri)

res = http.request(request)

puts "Response #{res.code} #{res.message}: #{res.body}"

Example of response

{
   "pagination":{
      "page":1,
      "total_pages":1,
      "entries":2,
      "total_entries":2
   },
   "transactions":[
      {
         "transaction":{
            "id":62946,
            "transaction_type":"switch",
            "serial_number":"520-501-438",
            "logical_number":"1116",
            "app_name":"main.posxml",
            "detail":"",
            "framework_version":"4.04",
            "status":"success",
            "sent":"null",
            "received":"null",
            "parsed":"null",
            "started_at":"2016-10-04T14:38:55Z",
            "finished_at":"2016-10-04T14:38:56Z"
         }
      },
      {
         "transaction":{
            "id":62945,
            "transaction_type":"switch",
            "serial_number":"520-501-438",
            "logical_number":"1116",
            "app_name":"main.posxml",
            "detail":"",
            "framework_version":"4.04",
            "status":"success",
            "sent":"null",
            "received":"null",
            "parsed":"null",
            "started_at":"2016-10-04T14:37:56Z",
            "finished_at":"2016-10-04T14:37:57Z"
         }
      }
   ]
}

Find transactions by status

Return an array with all transactions with the status defined on parameter &status.

Method and URL format

GET https://api.cloudwalk.io/{version}/transactions?access_token={token}&status={status}

Example of use

$ curl -X GET "https://api.cloudwalk.io/v1/transactions?access_token=$TOKEN&status=fail"
require 'net/http'

token = 'API_TOKEN'

uri = URI("https://api.cloudwalk.io/v1/transactions?access_token=#{token}&status=fail")

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

request = Net::HTTP::Get.new(uri.request_uri)

res = http.request(request)

puts "Response #{res.code} #{res.message}: #{res.body}"

Example of response

{
   "pagination":{
      "page":1,
      "total_pages":1,
      "entries":1,
      "total_entries":1
   },
   "transactions":[
      {
         "transaction":{
            "id":62955,
            "transaction_type":"switch",
            "serial_number":"520-541-412",
            "logical_number":"1116",
            "app_name":"main.posxml",
            "detail":"",
            "framework_version":"4.04",
            "status":"fail",
            "sent":"null",
            "received":"null",
            "parsed":"null",
            "started_at":"2016-10-04T13:17:12Z",
            "finished_at":"2016-10-04T13:17:14Z"
         }
      }
   ]
}

Find transactions by type

Return an array with all transactions with the record type defined on parameter &transaction_type.

Method and URL format

GET https://api.cloudwalk.io/{version}/transactions?access_token={token}&transaction_type={record type}

Example of use

$ curl -X GET "https://api.cloudwalk.io/v1/transactions?access_token=$TOKEN&transaction_type=get_asset"
require 'net/http'

token = 'API_TOKEN'

uri = URI("https://api.cloudwalk.io/v1/transactions?access_token=#{token}&transaction_type=get_asset")

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

request = Net::HTTP::Get.new(uri.request_uri)

res = http.request(request)

puts "Response #{res.code} #{res.message}: #{res.body}"

Example of response

{
   "pagination":{
      "page":1,
      "total_pages":1,
      "entries":1,
      "total_entries":1
   },
   "transactions":[
      {
         "transaction":{
            "id":63002,
            "transaction_type":"get_asset",
            "serial_number":"531-445-314",
            "logical_number":"1234",
            "app_name":"main.posxml",
            "detail":"",
            "framework_version":"4.04",
            "status":"success",
            "sent":"null",
            "received":"null",
            "parsed":"null",
            "started_at":"2016-10-04T13:18:32Z",
            "finished_at":"2016-10-04T13:18:37Z"
         }
      }
   ]
}

Find transactions by serial number

Return an array with all transactions with the serial number defined on parameter &serial_number.

Method and URL format

GET https://api.cloudwalk.io/{version}/transactions?access_token={token}&serial_number={serial number}

Example of use

$ curl -X GET "https://api.cloudwalk.io/v1/transactions?access_token=$TOKEN&serial_number=510-520-530"
require 'net/http'

token = 'API_TOKEN'

uri = URI("https://api.cloudwalk.io/v1/transactions?access_token=#{token}&serial_number=510-520-530")

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

request = Net::HTTP::Get.new(uri.request_uri)

res = http.request(request)

puts "Response #{res.code} #{res.message}: #{res.body}"

Example of response

{
   "pagination":{
      "page":1,
      "total_pages":1,
      "entries":1,
      "total_entries":1
   },
   "transactions":[
      {
         "transaction":{
            "id":63154,
            "transaction_type":"switch",
            "serial_number":"510-520-530",
            "logical_number":"1122",
            "app_name":"main.posxml",
            "detail":"",
            "framework_version":"4.04",
            "status":"success",
            "sent":"null",
            "received":"null",
            "parsed":"null",
            "started_at":"2016-10-04T14:21:11Z",
            "finished_at":"2016-10-04T14:21:14Z"
         }
      }
   ]
}

It is also possible to search for transactions of a specific logical number by defining the parameter &logical_number

Find transactions by app name

Return an array with all transactions with the app name defined on parameter &app_name.

Method and URL format

GET https://api.cloudwalk.io/{version}/transactions?access_token={token}&app_name={app name}

Example of use

$ curl -X GET "https://api.cloudwalk.io/v1/transactions?access_token=$TOKEN&app_name=main.posxml"
require 'net/http'

token = 'API_TOKEN'

uri = URI("https://api.cloudwalk.io/v1/transactions?access_token=#{token}&app_name=main.posxml")

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

request = Net::HTTP::Get.new(uri.request_uri)

res = http.request(request)

puts "Response #{res.code} #{res.message}: #{res.body}"

Example of response

{
   "pagination":{
      "page":1,
      "total_pages":1,
      "entries":1,
      "total_entries":1
   },
   "transactions":[
      {
         "transaction":{
            "id":63154,
            "transaction_type":"switch",
            "serial_number":"510-520-530",
            "logical_number":"1122",
            "app_name":"main.posxml",
            "detail":"",
            "framework_version":"4.04",
            "status":"success",
            "sent":"null",
            "received":"null",
            "parsed":"null",
            "started_at":"2016-10-04T14:21:11Z",
            "finished_at":"2016-10-04T14:21:14Z"
         }
      }
   ]
}

Find transactions by date

Return an array with all transactions within the interval defined on parameters &since and &until.

Method and URL format

GET https://api.cloudwalk.io/{version}/transactions?access_token={token}&since={inicial date}&until={final date}

Example of use

$ curl -X GET "https://api.cloudwalk.io/v1/transactions?access_token=$TOKEN&since=2016-10-03&until=2016-10-04"
require 'net/http'

token = 'API_TOKEN'

uri = URI("https://api.cloudwalk.io/v1/transactions?access_token=#{token}&since=2016-10-03&until=2016-10-04")

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

request = Net::HTTP::Get.new(uri.request_uri)

res = http.request(request)

puts "Response #{res.code} #{res.message}: #{res.body}"

Example of response

{
   "pagination":{
      "page":1,
      "total_pages":1,
      "entries":1,
      "total_entries":1
   },
   "transactions":[
      {
         "transaction":{
            "id":63154,
            "transaction_type":"switch",
            "serial_number":"510-520-530",
            "logical_number":"1122",
            "app_name":"main.posxml",
            "detail":"",
            "framework_version":"4.04",
            "status":"success",
            "sent":"null",
            "received":"null",
            "parsed":"null",
            "started_at":"2016-10-04T14:21:11Z",
            "finished_at":"2016-10-04T14:21:14Z"
         }
      }
   ]
}

Find transactions by multiple parameters

Return an array with all transactions with the defined parameters.

Method and URL format

GET https://api.cloudwalk.io/{version}/transactions?access_token={token}

Example of use

$ curl -X GET "https://api.cloudwalk.io/v1/transactions?access_token=$TOKEN&serial_number=510-520-530&status=fail"
require 'net/http'

token = 'API_TOKEN'

uri = URI("https://api.cloudwalk.io/v1/transactions?access_token=#{token}&serial_number=510-520-530&status=fail")

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

request = Net::HTTP::Get.new(uri.request_uri)

res = http.request(request)

puts "Response #{res.code} #{res.message}: #{res.body}"

Example of response

{
   "pagination":{
      "page":1,
      "total_pages":1,
      "entries":1,
      "total_entries":1
   },
   "transactions":[
      {
         "transaction":{
            "id":63231,
            "transaction_type":"switch",
            "serial_number":"510-520-530",
            "logical_number":"1122",
            "app_name":"main.posxml",
            "detail":"",
            "framework_version":"4.04",
            "status":"fail",
            "sent":"null",
            "received":"null",
            "parsed":"null",
            "started_at":"2016-10-04T15:38:01Z",
            "finished_at":"2016-10-04T15:38:04Z"
         }
      }
   ]
}

Parsed transaction data

Financial transactions generally use specific protocols such as ISO8583 or ISO20022. To simplify analysis, the data is parsed into the column parsed, as shown below:

Only successfully completed transactions are parsed (status = success)

{
  acquirer: 'acquirer-name',
  type: 'sale',                 // Other options: cancellation, refund, etc
  status: 'approved',           // Other options: denied
  status_reason: '0111',        // Authorizer response code
  capture_method: 'emv',        // Other options: magnetic-stripe, contactless, etc
  amount: 10000,                // Transaction amount in cents
  payment_method: 'debit',      // Other options: credit
  installment: {
    type: null,                 // Other options: merchant, issuer, etc
    quantity: null              // Other options: 1, 2, 3, etc
  },
  nsu: '123456789',             // CloudWalk NSU, generated on the application
  nsu_reference: '111222333',   // When present, represents the NSU of the transaction being cancelled
  authorization_code: '123',    // Host authorization code
  transaction_id: '987654321',  // Host transaction ID (or NSU from host)
  card: {
    holder_name: 'JOHN SMITH',  // When present
    brand: 'mastercard',        // Other options: visa, amex, etc
    expiration_date: '0221',    // Month (2 bytes) and Year (2 bytes)
    first_digits: '516230',     // First 6 digits (PCI compliance)
    last_digits: '0948'         // Last 4 digits (PCI compliance)
  },
  merchant: {
    id: '1152',                 // Merchant ID
    document: '11222333000455', // Merchant document (CNPJ or CPF)
    name: 'MERCHANT NAME'       // Merchant name
  },
  metadata: {}                  // Some sort of acquirer specific information
}