API Transaction

From Spiffy Stores Knowledge Base

The Spiffy Stores API Transaction object represents a transaction that has been applied to an order.

There are five types of transactions that can be applied to an order.

  • Sale: The amount of money transferred from the cardholder's account to pay the outstanding order.
  • Authorization: This represents the amount which has been reserved against the cardholder's account. No money changes hands until an authorization is captured.
  • Capture: This occurs only after an authorization has been approved, and records the actual transfer of funds from the cardholder's account.
  • Void: This represents the cancellation of a pending authorization or capture.
  • Refund: A full or partial return of captured funds to the cardholder can occur. A refund can only happen after a capture or sale is processed.

Transaction Properties

id { "id" : 123456789 }

A unique numeric identifier for the transaction. This ID is only used with the API interface.

order_id { "order_id" : 452983 }

The internal ID of the associated order.

order_number { "order_number" : 1045 }

A unique numeric identifier for the order that is used as a reference number for the store owner and customers. This is not the same as the internal ID of the order, which is only used to refer to orders within the API.

order_name { "order_name" : "#001045" }

This is the order_number, formatted according the the store preferences for order number formatting.

sequence { "sequence" : 1 }

The sequence number of the transaction.

amount { "amount" : 54.53 }

The value of the transaction.

fee { "fee" : 0.55 }

The value of the merchant fee associated with the transaction, if provided by the gateway.

authorization { "authorization" : "A235467-239934" }

The authorization code associated with the transaction.

transaction_id { "transaction_id" : "823048203" }

The transaction id that has been returned by the payment gateway.

created_at { "created_at" : "2015-10-24T18:26:31Z" }

The date and time when the transaction was created. The timestamp is in ISO 8601 format.

gateway { "gateway" : "Big Bank" }

The name of the payment gateway which processed the transaction.

kind { "kind" : "sale" }

The kind of transaction.
The following values can be returned: sale, authorization, capture, void and refund.

status { "status" : "success" }

The status of the transaction.
The following values can be returned: pending, failure, succes and error.

description { "description" : "Additional information about the transaction" }

In some cases some additional information may be returned by the payment gateway.

source_name { "source_name" : "web" }

The origin of the transaction. Currently, only web is returned.

currency { "currency" : "AUD" }

The currency used for the transaction.

payment_details { "payment_details" : {

  "avs_result_code" : null,
  "credit_card_bin" : "411111",
  "cvv_result_code" : null,
  "credit_card_number" : "4111 11XX XXXX 1234",
  "credit_card_company" : "Visa",
  "credit_card_issuing_bank" : "Big Bank",
  "minfraud_risk_score" : 0.15 }
Returns an object containing information about the credit card that was used for this transaction.

The following properties are supported:

  • avs_result_code - The response code from the Address Verification System. This code is only available from US, Canadian and UK payment gateways.
  • credit_card_number - The customer's partial credit card number.
  • credit_card_bin - The issuer identification number (IIN), formerly known as bank identification number (BIN) of the customer's credit card. This is made up of the first few digits of the credit card number.
  • credit_card_company - The name of the company who issued the customer's credit card.
  • credit_card_issuing_bank - The name of the financial institution that issued the customer's credit card.
  • cvv_result_code - The Response code from the credit card company indicating whether the customer entered the card security code correctly.
  • minfraud_risk_score - The risk score for the transaction, if available.

Endpoints

GET /api/orders/ORDER_ID/transactions.json

Return a list of transactions belonging to a specific order. Use the optional parameters to return specific transactions.

GET /api/transactions.json

Return a list of transactions belonging to a store. Use the optional parameters to return specific transactions.

Optional Parameters

limit Number of results returned. The default is 30, with a maximum of 50 in a single request.
page The number of the page to return. The number of results per page is set by the limit parameter. If more results are required, then submit the request again, increasing the page number each time.
ids A comma-separated list of transaction ids.
since_id Limit the results to only include objects which have an id greater than the given value.
created_at_min Return only the transactions created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the transactions created before the given date and time. Use the format "2014-12-31 12:00".
order_id Return all the transactions belonging to the specified order.
fields A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/transactions.json

HTTP/1.1 200 OK

{
  "transactions": [
    {
      "id": 34169,
      "order_id": 768969,
      "sequence": 1,
      "amount": "123.50",
      "kind": "sale",
      "gateway": "bogus",
      "status": "success",
      "description": null,
      "created_at": "2015-08-05T12:59:12-04:00",
      "authorization": "123456789",
      "transaction_id": "A3w47983",
      "currency": "AUD",
      "source_name": "web"
    }, ...
  ]
}

Examples using filters

GET /api/orders/234234/transactions.json?limit=10

GET /api/transactions.json?order_id=2322

GET /api/orders/ORDER_ID/transactions/count.json

Return a count of transactions belonging to an order.

GET /api/transactionss/count.json

Return a count of transactions belonging to a store.

Optional Parameters

since_id Limit the results to only include objects which have an id greater than the given value.
created_at_min Return only the transactions created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the transactions created before the given date and time. Use the format "2014-12-31 12:00".
order_id Return all the transactions belonging to the specified order.

Example Request and Response

GET /api/orders/12345/transactions/count.json

HTTP/1.1 200 OK

{
  "count": 3
}

Examples using filters

GET /api/transactions/count.json?order_id=2322

GET /api/orders/ORDER_ID/transactions/TRANSACTION_ID.json

Return a single transaction belonging to an order.

GET /api/transactions/TRANSACTION_ID.json

Return a single transaction belonging to a store.

Optional Parameters

fields A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/transactions/443169.json

HTTP/1.1 200 OK

{
  "transaction":
    {
      "id": 34169,
      "order_id": 768969,
      "sequence": 1,
      "amount": "123.50",
      "kind": "sale",
      ...
    }
}




Further Reference

Retrieved from "http://www.spiffystores.com.au/kb/index.php?title=API_Transaction&oldid=7274"