Developer API - Transações

  1. Atributos de uma transação
  2. Listagem de todas transações
  3. Consulta por status
  4. Consulta por tipo de registro
  5. Consulta por número de série
  6. Consulta por nome da aplicação
  7. Consulta por data
  8. Consulta por múltiplos parâmetros
  9. Dados parseados da transação

Atributos de uma transação

Os seguintes atributos compõe uma transação:

Nome Tipo Descrição
id Integer ID do registro
transaction_type String Tipo de registro: Liberação company, Transação switch ou Download get_asset
serial_number String Número de série do dispositivo
logical_number String Número lógico do dispositivo
app_name String Nome da aplicação que originou a transação
detail String Detalhes adicionais da transação (pode ser vazio)
framework_version String Versão do framework WALK instalado no dispositivo
status String Status do registro: Sucesso success, Processando running ou Falha fail
sent String Informação enviada para o host
received String Informação recebida do host
parsed Object Dados parseados da transação (somente aplicações financeiras)
started_at String Timestamp do início da transação (ISO 8601)
finished_at String Timestamp do fim da transação (ISO 8601)

Listagem de todas transações

Retorna um array com todas as transações.

Método e formato da URL

GET https://api.cloudwalk.io/{versão}/transactions?access_token={token}

Exemplo de utilização

$ 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}"

Exemplo de resposta

{
   "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"
         }
      }
   ]
}

Consulta por status

Retorna um array com todas as transações que possuem o status definido no parâmetro &status.

Método e formato da URL

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

Exemplo de utilização

$ 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}"

Exemplo de resposta

{
   "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"
         }
      }
   ]
}

Consulta por tipo de registro

Retorna um array com todas as transações que possuem o tipo de registro definido no parâmetro &transaction_type.

Método e formato da URL

GET https://api.cloudwalk.io/{versão}/transactions?access_token={token}&transaction_type={tipo de registro}

Exemplo de utilização

$ 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}"

Exemplo de resposta

{
   "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"
         }
      }
   ]
}

Consulta por número de série

Retorna um array com todas as transações que possuem o número de série definido no parâmetro &serial_number.

Método e formato da URL

GET https://api.cloudwalk.io/{versão}/transactions?access_token={token}&serial_number={número de série}

Exemplo de utilização

$ 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}"

Exemplo de resposta

{
   "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"
         }
      }
   ]
}

Também é possível consultar transações de um número lógico específico, bastando para isso definir o parâmetro &logical_number

Consulta por nome da aplicação

Retorna um array com todas as transações que possuem o nome da aplicação definido no parâmetro &app_name.

Método e formato da URL

GET https://api.cloudwalk.io/{versão}/transactions?access_token={token}&app_name={nome da aplicação}

Exemplo de utilização

$ 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}"

Exemplo de resposta

{
   "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"
         }
      }
   ]
}

Consulta por data

Retorna um array com todas as transações dentro do intervalo de data definido nos parâmetros &since e &until.

Método e formato da URL

GET https://api.cloudwalk.io/{versão}/transactions?access_token={token}&since={data inicial}&until={data final}

Exemplo de utilização

$ 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}"

Exemplo de resposta

{
   "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"
         }
      }
   ]
}

Consulta por múltiplos parâmetros

Retorna um array com todas as transações com os parâmetros definidos.

Método e formato da URL

GET https://api.cloudwalk.io/{versão}/transactions?access_token={token}

Exemplo de utilização

$ 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}"

Exemplo de resposta

{
   "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"
         }
      }
   ]
}

Dados parseados da transação

Transações financeiras geralmente utilizam protocolos específicos como ISO8583 ou ISO20022. Para simplificar possíveis análises, os dados são parseados na coluna parsed, conforme o exemplo abaixo:

Somente transações finalizadas com sucesso são parseadas (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
}