Transaction

Transactions are created for every order that results in an exchange of money.

#

There are five types of transactions:

  • Authorization: represents an amount reserved against the cardholder's funding source. Money does not change hands until an authorization is captured.
  • Sale: an authorization and capture performed together in a single step.
  • Capture: transfer of the money that was reserved during the authorization stage
  • Void: cancellation of a pending authorization or capture.
  • Refund: a partial or full return of captured funds to the cardholder. A refund can only happen after a capture is processed.

What can you do with Transaction?

The haravan API lets you do the following with the Transaction resource. More detailed versions of these general actions may be available:

Transaction Properties

amount
{ "amount" : "10.00" }

The amount of money that the transaction was for.

authorization
{ "authorization" : "null" }

The authorization code associated with the transaction.

created_at
{ "created_at" : "2012-03-13T16:09:54-04:00" }

The date and time when the transaction was created. The API returns this value in ISO 8601 format.

device_id
{ "device_id" : "null" }

The unique identifier for the device.

gateway
{ "gateway" : "bogus" }

The name of the gateway the transaction was issued through. A list of gateways can be found on haravan's Payment Gateway page.

source_name
{ "source_name" : "web" }

The origin of the transaction. This is set by haravan and cannot be overridden. Example values include: 'web', 'pos', 'iphone', 'android'

payment_details
{ "avs_result_code" : "null" }
{ "credit_card_bin" : "null" }
{ "cvv_result_code" : "null" }
{ "credit_card_number" : "•••• •••• •••• 4242" }
{ "credit_card_company" : "Visa" }

An object containing information about the credit card used for this transaction. It has the following properties:

  • avs_result_code: The Response code from AVS the address verification system. The code is a single letter; see this chart for the codes and their definitions.
  • 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_number: The customer's credit card number, with most of the leading digits redacted with Xs.
  • cvv_result_code: The Response code from the credit card company indicating whether the customer entered the card security code, a.k.a. card verification value, correctly. The code is a single letter or empty string; see this chart for the codes and their definitions.


id
{ "id" : "999225661" }

A unique numeric identifier for the transaction.

kind
{ "kind" : "capture" }

The kind of transaction:

  • authorization: Money that the customer has agreed to pay. Authorization period lasts for up to 7 to 30 days (depending on your payment service) while a store awaits for a customer's capture.
  • capture: Transfer of money that was reserved during the authorization of a shop.
  • sale: The combination of authorization and capture, performed in one single step.
  • void: The cancellation of a pending authorization or capture.
  • refund: The partial or full return of the captured money to the customer.


order_id
{ "order_id" : 450789469 }

A unique numeric identifier for the order.

receipt
{ "receipt" : "{ }" }


  • testcase:
  • authorization:


error_code
{ "error_code" : "invalid_cvc" }

A standardized error code, independent of the payment provider. Value can be null.

  • incorrect_number
  • invalid_number
  • invalid_expiry_date
  • invalid_cvc
  • expired_card
  • incorrect_cvc
  • incorrect_zip
  • incorrect_address
  • card_declined
  • processing_error
  • call_issuer
  • pick_up_card


status
{ "status" : "success" }

The status of the transaction. Valid values are: pending, failure, success or error.

test
{ "test" : true }

The option to use the transaction for testing purposes. Valid values are "true" or "false."

user_id
{ "user_id" : "null" }

The unique identifier for the user.

currency
{ "currency" : "USD" }

The three letter code (ISO 4217) for the currency used for the payment.

Endpoints

GET/admin/orders/450789469/transactions.json
since_id

Restrict results to after the specified ID

fields

comma-separated list of fields to include in the response

Get the Representation of all money transfers on a given order.

GET /admin/orders/#{id}/transactions.json
View Response
HTTP/1.1 200 OK
{
  "transactions": [
    {
      "amount": "209.00",
      "authorization": "authorization-key",
      "created_at": "2005-08-05T12:59:12-04:00",
      "currency": "USD",
      "gateway": "bogus",
      "id": 179259969,
      "kind": "refund",
      "location_id": null,
      "message": null,
      "order_id": 450789469,
      "parent_id": null,
      "status": "success",
      "test": false,
      "user_id": null,
      "device_id": null,
      "receipt": {},
      "error_code": null,
      "source_name": "web"
    },
    {
      "amount": "409.94",
      "authorization": "authorization-key",
      "created_at": "2005-08-01T11:57:11-04:00",
      "currency": "USD",
      "gateway": "bogus",
      "id": 389404469,
      "kind": "authorization",
      "location_id": null,
      "message": null,
      "order_id": 450789469,
      "parent_id": null,
      "status": "success",
      "test": false,
      "user_id": null,
      "device_id": null,
      "receipt": {
        "testcase": true,
        "authorization": "123456"
      },
      "error_code": null,
      "source_name": "web",
      "payment_details": {
        "avs_result_code": null,
        "credit_card_bin": null,
        "cvv_result_code": null,
        "credit_card_number": "•••• •••• •••• 4242",
        "credit_card_company": "Visa"
      }
    },
    {
      "amount": "250.94",
      "authorization": "authorization-key",
      "created_at": "2005-08-05T10:22:51-04:00",
      "currency": "USD",
      "gateway": "bogus",
      "id": 801038806,
      "kind": "capture",
      "location_id": null,
      "message": null,
      "order_id": 450789469,
      "parent_id": null,
      "status": "success",
      "test": false,
      "user_id": null,
      "device_id": null,
      "receipt": {},
      "error_code": null,
      "source_name": "web"
    }
  ]
}

Get the Representation of all money transfers on a given order after a specified ID

GET /admin/orders/#{id}/transactions.json?since_id=801038806
View Response
HTTP/1.1 200 OK
{
  "transactions": [
    {
      "amount": "10.00",
      "authorization": null,
      "created_at": "2015-03-28T13:33:38-04:00",
      "currency": "USD",
      "gateway": "bogus",
      "id": 1063838440,
      "kind": "capture",
      "location_id": null,
      "message": "Bogus Gateway: Forced success",
      "order_id": 450789469,
      "parent_id": 389404469,
      "status": "success",
      "test": true,
      "user_id": null,
      "device_id": null,
      "receipt": {},
      "error_code": null,
      "source_name": "755357713"
    }
  ]
}
GET/admin/orders/450789469/transactions/count.json

Count all a given order’s money transfers.

GET /admin/orders/#{id}/transactions/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 3
}
GET/admin/orders/450789469/transactions/389404469.json
fields

comma-separated list of fields to include in the response

Get the Representation of a specific transaction.

GET /admin/orders/#{id}/transactions/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "transaction": {
    "amount": "409.94",
    "authorization": "authorization-key",
    "created_at": "2005-08-01T11:57:11-04:00",
    "currency": "USD",
    "gateway": "bogus",
    "id": 389404469,
    "kind": "authorization",
    "location_id": null,
    "message": null,
    "order_id": 450789469,
    "parent_id": null,
    "status": "success",
    "test": false,
    "user_id": null,
    "device_id": null,
    "receipt": {
      "testcase": true,
      "authorization": "123456"
    },
    "error_code": null,
    "source_name": "web",
    "payment_details": {
      "avs_result_code": null,
      "credit_card_bin": null,
      "cvv_result_code": null,
      "credit_card_number": "•••• •••• •••• 4242",
      "credit_card_company": "Visa"
    }
  }
}
POST/admin/orders/450789469/transactions.json

Capture a specified amount on a previously authorized order.

POST /admin/orders/#{id}/transactions.json
{
  "transaction": {
    "amount": "10.00",
    "kind": "capture"
  }
}
View Response
HTTP/1.1 201 Created
{
  "transaction": {
    "amount": "10.00",
    "authorization": null,
    "created_at": "2015-03-28T13:33:37-04:00",
    "currency": "USD",
    "gateway": "bogus",
    "id": 1063838438,
    "kind": "capture",
    "location_id": null,
    "message": "Bogus Gateway: Forced success",
    "order_id": 450789469,
    "parent_id": 389404469,
    "status": "success",
    "test": true,
    "user_id": null,
    "device_id": null,
    "receipt": {},
    "error_code": null,
    "source_name": "755357713"
  }
}

Capture a previously authorized order for the full amount

POST /admin/orders/#{id}/transactions.json
{
  "transaction": {
    "kind": "capture"
  }
}
View Response
HTTP/1.1 201 Created
{
  "transaction": {
    "amount": "409.94",
    "authorization": null,
    "created_at": "2015-03-28T13:33:37-04:00",
    "currency": "USD",
    "gateway": "bogus",
    "id": 1063838439,
    "kind": "capture",
    "location_id": null,
    "message": "Bogus Gateway: Forced success",
    "order_id": 450789469,
    "parent_id": 389404469,
    "status": "success",
    "test": true,
    "user_id": null,
    "device_id": null,
    "receipt": {},
    "error_code": null,
    "source_name": "755357713"
  }
}