Transaction

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

There are five types of transactions:

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

Refund transactions must be created by using the Refund resource.

Note

An order can have no more than 100 transactions associated with it.

What you can 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": "ch_1AtJu6CktlpKSclI4zjeQb2t"

The authorization code associated with the transaction.

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

The date and time (ISO 8601 format) when the transaction was created.

currency
"currency": "USD"

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

device_id
"device_id": 1

The ID for the device.

error_code
"error_code": "invalid_cvc"

A standardized error code, independent of the payment provider. Valid values:

  • 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
gateway
"gateway": "shopify_payments"

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

id
"id": 999225661

The ID for the transaction.

kind
"kind": "capture"

The transaction's type. Valid values:

  • authorization: Money that the customer has agreed to pay. The authorization period can be between 7 and 30 days (depending on your payment service) while a store waits for a payment to be captured.
  • capture: A transfer of money that was reserved during the authorization of a shop.
  • sale: The authorization and capture of a payment performed in one single step.
  • void: The cancellation of a pending authorization or capture.
  • refund: The partial or full return of captured money to the customer.
message
"message": "Marked the Cash on Delivery (COD) payment as received"

A string generated by the payment provider with additional information about why the transaction succeeded or failed.

order_id
"order_id": 450789469

The ID for the order that the transaction is associated with.

payment_details
"payment_details": {
  "avs_result_code": "123456",
  "credit_card_bin": "M",
  "cvv_result_code": "M",
  "credit_card_number": "•••• •••• •••• 4242",
  "credit_card_company": "Visa"
}

Information about the credit card used for this transaction. It has the following properties:

  • avs_result_code: The response code from 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 that issued the customer's credit card.
  • credit_card_number: The customer's credit card number, with most of the leading digits redacted.
  • cvv_result_code: The response code from the credit card company indicating whether the customer entered the card security code, or card verification value, correctly. The code is a single letter or empty string; see this chart for the codes and their definitions.
parent_id
"parent_id": 584698724408

The ID of an associated authorization transaction. Include this in the POST request when you create a capture transaction to associate it with an authorization.

receipt
"receipt": {}

A transaction receipt attached to the transaction by the gateway. The value of this field depends on which gateway the shop is using.

source_name
"source_name": "web"

The origin of the transaction. This is set by Shopify and can't be overridden. Example values: web, pos, iphone, and android.

status
"status": "success"

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

test
"test": true

Whether the transaction is a test transaction.

user_id
"user_id": 106045196

The ID for the user who was logged into the Shopify POS device when the order was processed, if applicable.

Endpoints

GET /admin/orders/450789469/transactions.json
Retrieves a list of transactions.
since_id

Retrieve only transactions after the specified ID.

fields

Show only certain fields, specifed by a comma-separated list of fields names.

Retrieve an order's transactions

GET /admin/orders/#{order_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": 801038806,
      "device_id": null,
      "receipt": {},
      "error_code": null,
      "source_name": "web",
      "admin_graphql_api_id": "gid://shopify/OrderTransaction/179259969"
    },
    {
      "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",
      "admin_graphql_api_id": "gid://shopify/OrderTransaction/389404469",
      "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": 389404469,
      "device_id": null,
      "receipt": {},
      "error_code": null,
      "source_name": "web",
      "admin_graphql_api_id": "gid://shopify/OrderTransaction/801038806"
    }
  ]
}

Retrieve an order's transactions after a specified ID

GET /admin/orders/#{order_id}/transactions.json?since_id=801038806
View Response
HTTP/1.1 200 OK
{
  "transactions": [
    {
      "id": 1072844665,
      "order_id": 450789469,
      "amount": "10.00",
      "kind": "capture",
      "gateway": "bogus",
      "status": "success",
      "message": "Bogus Gateway: Forced success",
      "created_at": "2018-07-05T12:57:56-04: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",
      "admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844665"
    }
  ]
}
GET /admin/orders/450789469/transactions/count.json
Retrieves a count of an order's transactions.

Count an order's transactions

GET /admin/orders/#{order_id}/transactions/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 3
}
GET /admin/orders/450789469/transactions/389404469.json
Retrieves a specific transaction.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a specific transaction for an order

GET /admin/orders/#{order_id}/transactions/#{transaction_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",
    "admin_graphql_api_id": "gid://shopify/OrderTransaction/389404469",
    "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
Creates a transaction for an order.

Capture a specified amount on an authorized order, and associate the capture with an authorization by including its ID

POST /admin/orders/#{order_id}/transactions.json
{
  "transaction": {
    "amount": "10.00",
    "kind": "capture",
    "parent_id": 389404469
  }
}
View Response
HTTP/1.1 201 Created
{
  "transaction": {
    "id": 1072844666,
    "order_id": 450789469,
    "amount": "10.00",
    "kind": "capture",
    "gateway": "bogus",
    "status": "success",
    "message": "Bogus Gateway: Forced success",
    "created_at": "2018-07-05T12:57:59-04: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",
    "admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844666"
  }
}

Capture the full amount for an authorized order, and associate the capture with an authorization by including its authorization code

POST /admin/orders/#{order_id}/transactions.json
{
  "transaction": {
    "kind": "capture",
    "authorization": "authorization-key"
  }
}
View Response
HTTP/1.1 201 Created
{
  "transaction": {
    "id": 1072844667,
    "order_id": 450789469,
    "amount": "409.94",
    "kind": "capture",
    "gateway": "bogus",
    "status": "success",
    "message": "Bogus Gateway: Forced success",
    "created_at": "2018-07-05T12:58:00-04: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",
    "admin_graphql_api_id": "gid://shopify/OrderTransaction/1072844667"
  }
}

Sign up for a Partner account to get started.

Sign up