Transaction

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

Transaction - 图1

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 plain "amount": "10.00" The amount of money included in the transaction. If you don’t provide a value for amount, then it defaults to the total cost of the order (even if a previous transaction has been made towards it).
authorization plain "authorization": "ch_1AtJu6CktlpKSclI4zjeQb2t" The authorization code associated with the transaction.
authorization_expires_at plain "authorization_expires_at": "2021-03-13T16:09:54-04:00" The date and time (ISO 8601 format) when the Shopify Payments authorization expires.
created_at READ-ONLY plain "created_at": "2012-03-13T16:09:54-04:00" The date and time (ISO 8601 format) when the transaction was created.
currency plain "currency": "USD" The three-letter code (ISO 4217 format) for the currency used for the payment.
device_id READ-ONLY plain "device_id": 1 The ID for the device.
error_code READ-ONLY plain "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
extended_authorization_attributes plain "extended_authorization_attributes": { "standard_authorization_expires_at": "2020-10-08T00:00:00-04:00", "extended_authorization_expires_at": "2020-10-30T00:00:00-04:00" } The attributes associated with a Shopify Payments extended authorization period. It has the following properties:
+ standard_authorization_expires_at: The date and time (ISO 8601 format) when the standard authorization period expires. After expiry, an extended authorization fee is applied upon capturing the payment.
+ extended_authorization_expires_at: The date and time (ISO 8601 format) when the extended authorization period expires. After expiry, the merchant can’t capture the payment.
extended_authorization_attributes
are available on the Retrieve a specific transaction
endpoint only to stores on the Shopify Plus
plan that use Shopify Payments. To learn more about extended authorization periods, refer to Payment authorization
.
gateway plain "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 READ-ONLY plain "id": 999225661 The ID for the transaction.
kind REQUIRED plain "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.
location_id READ-ONLY plain "id": 49202758 The ID of the physical location where the transaction was processed.
message READ-ONLY plain "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 plain "order_id": 450789469 The ID for the order that the transaction is associated with.
payment_details READ-ONLY plain "payment_details": { "credit_card_bin": "123456", "avs_result_code": "Y", "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:
+ 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.
+ avs_result_code: The response code from the address verification system. The code is always a single letter. Refer to this chart for the codes and their definitions.
+ 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.
+ credit_card_number: The customer’s credit card number, with most of the leading digits redacted.
+ credit_card_company: The name of the company that issued the customer’s credit card.
parent_id plain "parent_id": 584698724408 The ID of an associated transaction.
+ For capture transactions, the parent needs to be an authorization transaction.
+ For void transactions, the parent needs to be an authorization transaction.
+ For refund transactions, the parent needs to be a capture or sale transaction.
processed_at plain "processed_at": "2018-01-10T11:00:00-05:00" The date and time (ISO 8601 format) when a transaction was processed. This value is the date that’s used in the analytic reports. By default, it matches the created_at value. If you’re importing transactions from an app or another platform, then you can set processed_at to a date and time in the past to match when the original transaction was processed.
receipt READ-ONLY plain "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 READ-ONLY plain "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 plain "status": "success" The status of the transaction. Valid values: pending, failure, success, and error.
test plain "test": true Whether the transaction is a test transaction.
user_id plain "user_id": 106045196 The ID for the user who was logged into the Shopify POS device when the order was processed, if applicable.
currency_exchange_adjustment plain "currency_exchange_adjustment": { "id": 1, "adjustment": "-0.01", "original_amount": "-53.62", "final_amount": "-53.63", "currency": "CAD" } An adjustment on the transaction showing the amount lost or gained due to fluctuations in the currency exchange rate. It has the following properties:
+ ID: The ID of the adjustment.
+ adjustment: The difference between the amounts on the associated transaction and the parent transaction.
+ original_amount: The amount of the parent transaction in the shop currency.
+ final_amount: The amount of the associated transaction in the shop currency.
+ currency: The shop currency.
Requires the header X-Shopify-Api-Features = include-currency-exchange-adjustments
.

Endpoints

GET/admin/api/2021-01/orders/{order_id}/transactions.json

Retrieves a list of transactions.

Transactions attached to multi-currency orders are in the presentment currency by default. To retrieve transactions in the shop currency, include the URL parameter in_shop_currency=true.

since_id Retrieve only transactions after the specified ID.
fields Show only certain fields, specifed by a comma-separated list of fields names.
in_shop_currency Show amounts in the shop currency.
(default: false
)

Retrieve an order’s transactions

GET /admin/api/2021-01/orders/450789469/transactions.json

View Response

Retrieve an order’s transactions after a specified ID

GET /admin/api/2021-01/orders/450789469/transactions.json?since_id=801038806

View Response

GET/admin/api/2021-01/orders/{order_id}/transactions/count.json Retrieves a count of an order’s transactions.

Count an order’s transactions

GET /admin/api/2021-01/orders/450789469/transactions/count.json

View Response

GET/admin/api/2021-01/orders/{order_id}/transactions/{transaction_id}.json

Retrieves a specific transaction.

Transactions attached to multi-currency orders are in the presentment currency by default. To retrieve transactions in the shop currency, include the URL parameter in_shop_currency=true.

extended_authorization_attributes are available on this endpoint only to stores on the Shopify Plus plan that use Shopify Payments. To learn more about extended authorization periods, refer to Payment authorization.

fields Show only certain fields, specified by a comma-separated list of field names.
in_shop_currency Show amounts in the shop currency.
(default: false
)

Retrieve a specific transaction for an order

GET /admin/api/2021-01/orders/450789469/transactions/389404469.json

View Response

POST/admin/api/2021-01/orders/{order_id}/transactions.json

Caution

For multi-currency orders, the currency property is required when creating refund and capture transactions. The value should be the presentment currency from the order. For more information, see Migrating to support multiple currencies.

Creates a transaction for an order.

source The origin of the transaction. Set to external to create a cash transaction for the associated order.

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

POST /admin/api/2021-01/orders/450789469/transactions.json

{

“transaction”: {

  1. "currency": "USD",
  3. "amount": "10.00",
  5. "kind": "capture",
  7. "parent_id": 389404469

}

}

View Response

Void a transaction

POST /admin/api/2021-01/orders/450789469/transactions.json

{

“transaction”: {

  1. "currency": "USD",
  3. "amount": "10.00",
  5. "kind": "void",
  7. "parent_id": 389404469

}

}

View Response

Create a test transaction

POST /admin/api/2021-01/orders/450789469/transactions.json

{

“transaction”: {

  1. "currency": "USD",
  3. "amount": "10.00",
  5. "kind": "capture",
  7. "parent_id": 389404469,
  9. "test": true

}

}

View Response

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

POST /admin/api/2021-01/orders/450789469/transactions.json

{

“transaction”: {

  1. "kind": "capture",
  3. "authorization": "authorization-key"

}

}

View Response