Transaction

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

Transaction

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.

Refund transactions must be created through a Refund.

What can you do with Transaction?

The Shopify 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 Shopify's Payment Gateway page.

source_name
{ "source_name" : "web" }

The origin of the transaction. This is set by Shopify 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" : {} }

A transaction reciept attached to the transaction by the gateway. The value of this field will vary depending on which gateway the shop is using.

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": [
    {
      "id": 179259969,
      "order_id": 450789469,
      "amount": "209.00",
      "kind": "refund",
      "gateway": "bogus",
      "status": "success",
      "message": null,
      "created_at": "2005-08-05T12:59:12-04:00",
      "test": false,
      "authorization": "authorization-key",
      "currency": "USD",
      "location_id": null,
      "user_id": null,
      "parent_id": null,
      "device_id": null,
      "receipt": {},
      "error_code": null,
      "source_name": "web"
    },
    {
      "id": 389404469,
      "order_id": 450789469,
      "amount": "409.94",
      "kind": "authorization",
      "gateway": "bogus",
      "status": "success",
      "message": null,
      "created_at": "2005-08-01T11:57:11-04:00",
      "test": false,
      "authorization": "authorization-key",
      "currency": "USD",
      "location_id": null,
      "user_id": null,
      "parent_id": null,
      "device_id": null,
      "receipt": {
        "testcase": true,
        "authorization": "123456"
      },
      "error_code": null,
      "source_name": "web",
      "payment_details": {
        "credit_card_bin": null,
        "avs_result_code": null,
        "cvv_result_code": null,
        "credit_card_number": "•••• •••• •••• 4242",
        "credit_card_company": "Visa"
      }
    },
    {
      "id": 801038806,
      "order_id": 450789469,
      "amount": "250.94",
      "kind": "capture",
      "gateway": "bogus",
      "status": "success",
      "message": null,
      "created_at": "2005-08-05T10:22:51-04:00",
      "test": false,
      "authorization": "authorization-key",
      "currency": "USD",
      "location_id": null,
      "user_id": null,
      "parent_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": [
    {
      "id": 1068278465,
      "order_id": 450789469,
      "amount": "10.00",
      "kind": "capture",
      "gateway": "bogus",
      "status": "success",
      "message": "Bogus Gateway: Forced success",
      "created_at": "2016-11-09T13:47:36-05:00",
      "test": true,
      "authorization": null,
      "currency": "USD",
      "location_id": null,
      "user_id": null,
      "parent_id": 389404469,
      "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": {
    "id": 389404469,
    "order_id": 450789469,
    "amount": "409.94",
    "kind": "authorization",
    "gateway": "bogus",
    "status": "success",
    "message": null,
    "created_at": "2005-08-01T11:57:11-04:00",
    "test": false,
    "authorization": "authorization-key",
    "currency": "USD",
    "location_id": null,
    "user_id": null,
    "parent_id": null,
    "device_id": null,
    "receipt": {
      "testcase": true,
      "authorization": "123456"
    },
    "error_code": null,
    "source_name": "web",
    "payment_details": {
      "credit_card_bin": null,
      "avs_result_code": null,
      "cvv_result_code": null,
      "credit_card_number": "•••• •••• •••• 4242",
      "credit_card_company": "Visa"
    }
  }
}
POST /admin/orders/450789469/transactions.json

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": {
    "id": 1068278463,
    "order_id": 450789469,
    "amount": "409.94",
    "kind": "capture",
    "gateway": "bogus",
    "status": "success",
    "message": "Bogus Gateway: Forced success",
    "created_at": "2016-11-09T13:47:35-05:00",
    "test": true,
    "authorization": null,
    "currency": "USD",
    "location_id": null,
    "user_id": null,
    "parent_id": 389404469,
    "device_id": null,
    "receipt": {},
    "error_code": null,
    "source_name": "755357713"
  }
}

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": {
    "id": 1068278464,
    "order_id": 450789469,
    "amount": "10.00",
    "kind": "capture",
    "gateway": "bogus",
    "status": "success",
    "message": "Bogus Gateway: Forced success",
    "created_at": "2016-11-09T13:47:35-05:00",
    "test": true,
    "authorization": null,
    "currency": "USD",
    "location_id": null,
    "user_id": null,
    "parent_id": 389404469,
    "device_id": null,
    "receipt": {},
    "error_code": null,
    "source_name": "755357713"
  }
}