Transactions are created for every order that results in an exchange of money.
{{ '/api/reference/transaction.png' | image }}
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 more than one authorization transaction associated with it. This might happen when an order is edited or when a post-purchase upsell is added to the order. To be notified when an order is edited subscribe to the OrderEdit webhook.
If your app captures payments, you should make a GET request to the /admin/api/{version}/orders/{order_id}/transactions.json endpoint to retrieve the
authorization transactions associated with an order. Then, to complete the full order payment capture, you should use the authorization or parent_id
properties in separate capture POST requests to the same endpoint for each authorization transaction.
Note
An order can have no more than 100 transactions associated with it.
## Resource Properties
### Transaction
* amount: 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).
* Type: x-string
* Example: "10.00"
* authorization: The authorization code associated with the transaction.
* Type: x-string
* Example: "ch_1AtJu6CktlpKSclI4zjeQb2t"
* authorization_expires_at: The date and time (ISO 8601 format) when the Shopify Payments authorization expires.
* Type: x-string
* Example: "2021-03-13T16:09:54-04:00"
* created_at: The date and time (ISO 8601 format) when the transaction was created.
* Type: x-string
* Example: "2012-03-13T16:09:54-04:00"
* currency:
The three-letter code (ISO 4217 format) for the currency used for the payment.
* Type: x-string
* Example: "USD"
* device_id: The ID for the device.
* Type: x-string
* Example: 1
* error_code: 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
* Type: x-string
* Example: "invalid_cvc"
* extended_authorization_attributes: The attributes associated with a Shopify Payments extended authorization period. It has the following attributes:
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 for an order endpoint only if the following criteria applies:
The transaction being retrieved is an extended authorization, which is determined by the capture_before date in the charge.
If the criteria isn't met, then an empty JSON is returned for extended_authorization_attributes.
To learn more about extended authorization periods, refer to Payment authorization.
* Type: x-string
* Example: {"standard_authorization_expires_at"=>"2020-10-08T00:00:00-04:00", "extended_authorization_expires_at"=>"2020-10-30T00:00:00-04:00"}
* gateway: The name of the gateway the transaction was issued through. A list of gateways can be found on Shopify's payment gateways page.
* Type: x-string
* Example: "shopify_payments"
* id: The ID for the transaction.
* Type: x-string
* Example: 999225661
* kind: 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.
* Type: x-string
* Example: "capture"
* location_id: The ID of the physical location where the transaction was processed.
* Type: x-string
* Example: {"id"=>49202758}
* message: A string generated by the payment provider with additional information about why the transaction succeeded or failed.
* Type: x-string
* Example: "Marked the Stripe payment as received"
* order_id: The ID for the order that the transaction is associated with.
* Type: x-string
* Example: 450789469
* payment_details: Information about the payment method used for this transaction. It has the following attributes:
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.
credit_card_name: The holder of the credit card.
credit_card_wallet: The wallet type where this credit card was retrieved from.
credit_card_expiration_month: The month in which the credit card expires.
credit_card_expiration_year: The year in which the credit card expires.
buyer_action_info: Details for payment methods that require additional buyer action to complete the order transaction.
payment_method_name: The name of the payment method used by the buyer to complete the order transaction.
* Type: x-string
* Example: {"credit_card_bin"=>"123456", "avs_result_code"=>"Y", "cvv_result_code"=>"M", "credit_card_number"=>"•••• •••• •••• 4242", "credit_card_company"=>"Visa", "credit_card_name"=>"John Smith", "credit_card_wallet"=>"shopify_pay", "credit_card_expiration_month"=>10, "credit_card_expiration_year"=>2028, "buyer_action_info"=>{"multibanco"=>{"Entity"=>"12345", "Reference"=>"999999999"}}, "payment_method_name"=>"multibanco"}
* parent_id: 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.
* Type: x-string
* Example: 584698724408
* payments_refund_attributes: The attributes associated with a Shopify Payments refund. It has the following attributes:
status: The current status of the refund. Valid values: pending, failure, success, and error.
acquirer_reference_number: A unique number associated with the transaction that can be used to track the refund. This property has a value only for transactions completed with Visa or Mastercard.
payments_refund_attributes are available on any JSON serialization of the order transaction only if the following criteria apply:
The order transaction kind is either refund or void.
If the criteria isn't met, then the payments_refund_attributes property is omitted.
* Type: x-string
* Example: {"status"=>"success", "acquirer_reference_number"=>"123456789012345678901234"}
* processed_at: 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.
* Type: x-string
* Example: "2018-01-10T11:00:00-05:00"
* receipt: A transaction receipt attached to the transaction by the gateway. The value of this field depends on which gateway the shop is using.
* Type: x-string
* Example: {}
* source_name: The origin of the transaction. This is set by Shopify and can't be overridden. Example values (not an exhaustive list): web, pos, iphone, and android.
* Type: x-string
* Example: "web"
* status: The status of the transaction. Valid values: pending, failure, success, and error.
* Type: x-string
* Example: "success"
* total_unsettled_set: Specifies the available amount with currency to capture on the gateway in shop and presentment currencies. Only available when an amount is capturable or manually mark as paid.
* Type: x-string
* Example: {"presentment_money"=>{"amount"=>"171.8", "currency"=>"USD"}, "shop_money"=>{"amount"=>"171.8", "currency"=>"USD"}}
* test: Whether the transaction is a test transaction.
* Type: x-string
* Example: true
* user_id: The ID for the user who was logged into the Shopify POS device when the order was processed, if applicable.
* Type: x-string
* Example: 106045196
* currency_exchange_adjustment: An adjustment on the transaction showing the amount lost or gained due to fluctuations in the currency exchange rate. It has the following attributes:
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.
* Type: x-string
* Example: {"id"=>1, "adjustment"=>"-0.01", "original_amount"=>"-53.62", "final_amount"=>"-53.63", "currency"=>"CAD"}
* manual_payment_gateway: Whether payment gateway used is manual.
* Type: boolean
* Example: false
## Retrieves a list of transactions
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.
### Endpoint
/admin/api/#{api_version}/orders/{order_id}/transactions.json (GET)
### Parameters
* api_version (required):
* order_id (required):
* fields: Show only certain fields, specifed by a comma-separated list of fields names.
* in_shop_currency: Show amounts in the shop currency.
* since_id: Retrieve only transactions after the specified ID.
### Responses
#### 200
Retrieves a list of transactions
Examples:
##### Retrieve an order's transactions
Request:
```
GET /admin/api/2024-04/orders/450789469/transactions.json
```
Response:
```
HTTP/1.1 200 OK
{"transactions":[{"id":179259969,"order_id":450789469,"kind":"refund","gateway":"bogus","status":"success","message":null,"created_at":"2005-08-05T12:59:12-04:00","test":false,"authorization":"authorization-key","location_id":null,"user_id":null,"parent_id":801038806,"processed_at":"2005-08-05T12:59:12-04:00","device_id":null,"error_code":null,"source_name":"web","receipt":{},"currency_exchange_adjustment":null,"amount":"209.00","currency":"USD","payment_id":"#1001.3","total_unsettled_set":{"presentment_money":{"amount":"348.0","currency":"USD"},"shop_money":{"amount":"348.0","currency":"USD"}},"manual_payment_gateway":false,"admin_graphql_api_id":"gid://shopify/OrderTransaction/179259969"},{"id":389404469,"order_id":450789469,"kind":"authorization","gateway":"bogus","status":"success","message":null,"created_at":"2005-08-01T11:57:11-04:00","test":false,"authorization":"authorization-key","location_id":null,"user_id":null,"parent_id":null,"processed_at":"2005-08-01T11:57:11-04:00","device_id":null,"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","buyer_action_info":null,"credit_card_name":null,"credit_card_wallet":null,"credit_card_expiration_month":null,"credit_card_expiration_year":null,"payment_method_name":"visa"},"receipt":{"testcase":true,"authorization":"123456"},"currency_exchange_adjustment":null,"amount":"598.94","currency":"USD","payment_id":"#1001.1","total_unsettled_set":{"presentment_money":{"amount":"348.0","currency":"USD"},"shop_money":{"amount":"348.0","currency":"USD"}},"manual_payment_gateway":false,"admin_graphql_api_id":"gid://shopify/OrderTransaction/389404469"},{"id":801038806,"order_id":450789469,"kind":"capture","gateway":"bogus","status":"success","message":null,"created_at":"2005-08-05T10:22:51-04:00","test":false,"authorization":"authorization-key","location_id":null,"user_id":null,"parent_id":389404469,"processed_at":"2005-08-05T10:22:51-04:00","device_id":null,"error_code":null,"source_name":"web","receipt":{},"currency_exchange_adjustment":null,"amount":"250.94","currency":"USD","payment_id":"#1001.2","total_unsettled_set":{"presentment_money":{"amount":"348.0","currency":"USD"},"shop_money":{"amount":"348.0","currency":"USD"}},"manual_payment_gateway":false,"admin_graphql_api_id":"gid://shopify/OrderTransaction/801038806"}]}
```
##### Retrieve an order's transactions after a specified ID
Request:
```
GET /admin/api/2024-04/orders/450789469/transactions.json
```
Response:
```
HTTP/1.1 200 OK
{"transactions":[{"id":1068278478,"order_id":450789469,"kind":"capture","gateway":"bogus","status":"success","message":"Bogus Gateway: Forced success","created_at":"2024-09-24T15:32:31-04:00","test":true,"authorization":null,"location_id":null,"user_id":null,"parent_id":389404469,"processed_at":"2024-09-24T15:32:32-04:00","device_id":null,"error_code":null,"source_name":"755357713","payment_details":{"credit_card_bin":null,"avs_result_code":null,"cvv_result_code":null,"credit_card_number":"•••• •••• •••• 4242","credit_card_company":"Visa","buyer_action_info":null,"credit_card_name":null,"credit_card_wallet":null,"credit_card_expiration_month":null,"credit_card_expiration_year":null,"payment_method_name":"visa"},"receipt":{},"currency_exchange_adjustment":null,"amount":"10.00","currency":"USD","payment_id":"c901414060.1","total_unsettled_set":{"presentment_money":{"amount":"338.0","currency":"USD"},"shop_money":{"amount":"338.0","currency":"USD"}},"manual_payment_gateway":false,"admin_graphql_api_id":"gid://shopify/OrderTransaction/1068278478"}]}
```
## Creates a transaction for an order
Creates a transaction for an order.
### Endpoint
/admin/api/#{api_version}/orders/{order_id}/transactions.json (POST)
### Parameters
* api_version (required):
* order_id (required):
* source: An optional origin of the transaction. Set to external to import a cash transaction for the associated order.
### Responses
#### 201
Creates a transaction for an order
Examples:
##### Capture a specified amount on an authorized order, and associate the capture with an authorization by including its ID
Request:
```
POST /admin/api/2024-04/orders/450789469/transactions.json
{"transaction":{"currency":"USD","amount":"10.00","kind":"capture","parent_id":389404469}}
```
Response:
```
HTTP/1.1 201 Created
{"transaction":{"id":1068278476,"order_id":450789469,"kind":"capture","gateway":"bogus","status":"success","message":"Bogus Gateway: Forced success","created_at":"2024-09-24T15:32:30-04:00","test":true,"authorization":null,"location_id":null,"user_id":null,"parent_id":389404469,"processed_at":"2024-09-24T15:32:30-04:00","device_id":null,"error_code":null,"source_name":"755357713","payment_details":{"credit_card_bin":null,"avs_result_code":null,"cvv_result_code":null,"credit_card_number":"•••• •••• •••• 4242","credit_card_company":"Visa","buyer_action_info":null,"credit_card_name":null,"credit_card_wallet":null,"credit_card_expiration_month":null,"credit_card_expiration_year":null,"payment_method_name":"visa"},"receipt":{},"currency_exchange_adjustment":null,"amount":"10.00","currency":"USD","payment_id":"c901414060.1","total_unsettled_set":{"presentment_money":{"amount":"588.94","currency":"USD"},"shop_money":{"amount":"588.94","currency":"USD"}},"manual_payment_gateway":false,"admin_graphql_api_id":"gid://shopify/OrderTransaction/1068278476"}}
```
##### Capture the full amount for one authorization on an order, and associate the capture with an authorization by including its authorization code
Request:
```
POST /admin/api/2024-04/orders/450789469/transactions.json
{"transaction":{"kind":"capture","authorization":"authorization-key"}}
```
Response:
```
HTTP/1.1 201 Created
{"transaction":{"id":1068278464,"order_id":450789469,"kind":"capture","gateway":"bogus","status":"success","message":"Bogus Gateway: Forced success","created_at":"2024-09-24T15:32:18-04:00","test":true,"authorization":null,"location_id":null,"user_id":null,"parent_id":389404469,"processed_at":"2024-09-24T15:32:18-04:00","device_id":null,"error_code":null,"source_name":"755357713","payment_details":{"credit_card_bin":null,"avs_result_code":null,"cvv_result_code":null,"credit_card_number":"•••• •••• •••• 4242","credit_card_company":"Visa","buyer_action_info":null,"credit_card_name":null,"credit_card_wallet":null,"credit_card_expiration_month":null,"credit_card_expiration_year":null,"payment_method_name":"visa"},"receipt":{},"currency_exchange_adjustment":null,"amount":"598.94","currency":"USD","payment_id":"c901414060.1","total_unsettled_set":{"presentment_money":{"amount":"0.0","currency":"USD"},"shop_money":{"amount":"0.0","currency":"USD"}},"manual_payment_gateway":false,"admin_graphql_api_id":"gid://shopify/OrderTransaction/1068278464"}}
```
##### Create a test transaction
Request:
```
POST /admin/api/2024-04/orders/450789469/transactions.json
{"transaction":{"currency":"USD","amount":"10.00","kind":"capture","parent_id":389404469,"test":true}}
```
Response:
```
HTTP/1.1 201 Created
{"transaction":{"id":1068278471,"order_id":450789469,"kind":"capture","gateway":"bogus","status":"success","message":"Bogus Gateway: Forced success","created_at":"2024-09-24T15:32:25-04:00","test":true,"authorization":null,"location_id":null,"user_id":null,"parent_id":389404469,"processed_at":"2024-09-24T15:32:25-04:00","device_id":null,"error_code":null,"source_name":"755357713","payment_details":{"credit_card_bin":null,"avs_result_code":null,"cvv_result_code":null,"credit_card_number":"•••• •••• •••• 4242","credit_card_company":"Visa","buyer_action_info":null,"credit_card_name":null,"credit_card_wallet":null,"credit_card_expiration_month":null,"credit_card_expiration_year":null,"payment_method_name":"visa"},"receipt":{},"currency_exchange_adjustment":null,"amount":"10.00","currency":"USD","payment_id":"c901414060.1","total_unsettled_set":{"presentment_money":{"amount":"588.94","currency":"USD"},"shop_money":{"amount":"588.94","currency":"USD"}},"manual_payment_gateway":false,"admin_graphql_api_id":"gid://shopify/OrderTransaction/1068278471"}}
```
##### Void a transaction
Request:
```
POST /admin/api/2024-04/orders/450789469/transactions.json
{"transaction":{"currency":"USD","amount":"10.00","kind":"void","parent_id":389404469}}
```
Response:
```
HTTP/1.1 201 Created
{"transaction":{"id":1068278487,"order_id":450789469,"kind":"void","gateway":"bogus","status":"success","message":"Bogus Gateway: Forced success","created_at":"2024-09-24T15:32:40-04:00","test":true,"authorization":null,"location_id":null,"user_id":null,"parent_id":389404469,"processed_at":"2024-09-24T15:32:40-04:00","device_id":null,"error_code":null,"source_name":"755357713","payment_details":{"credit_card_bin":null,"avs_result_code":null,"cvv_result_code":null,"credit_card_number":"•••• •••• •••• 4242","credit_card_company":"Visa","buyer_action_info":null,"credit_card_name":null,"credit_card_wallet":null,"credit_card_expiration_month":null,"credit_card_expiration_year":null,"payment_method_name":"visa"},"receipt":{},"currency_exchange_adjustment":null,"amount":"0.00","currency":"USD","payment_id":"c901414060.1","total_unsettled_set":{"presentment_money":{"amount":"0.0","currency":"USD"},"shop_money":{"amount":"0.0","currency":"USD"}},"manual_payment_gateway":false,"admin_graphql_api_id":"gid://shopify/OrderTransaction/1068278487"}}
```
## Retrieves a count of an order's transactions
Retrieves a count of an order's transactions.
### Endpoint
/admin/api/#{api_version}/orders/{order_id}/transactions/count.json (GET)
### Parameters
* api_version (required):
* order_id (required):
### Responses
#### 200
Retrieves a count of an order's transactions
Examples:
##### Count an order's transactions
Request:
```
GET /admin/api/unstable/orders/450789469/transactions/count.json
```
Response:
```
HTTP/1.1 200 OK
{"count":3}
```
## Retrieves a specific transaction
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.
### Endpoint
/admin/api/#{api_version}/orders/{order_id}/transactions/{transaction_id}.json (GET)
### Parameters
* api_version (required):
* order_id (required):
* transaction_id (required):
* fields: Show only certain fields, specified by a comma-separated list of field names.
* in_shop_currency: Show amounts in the shop currency.
### Responses
#### 200
Retrieves a specific transaction
Examples:
##### Retrieve a specific transaction for an order
Request:
```
GET /admin/api/2024-04/orders/450789469/transactions/389404469.json
```
Response:
```
HTTP/1.1 200 OK
{"transaction":{"id":389404469,"order_id":450789469,"kind":"authorization","gateway":"bogus","status":"success","message":null,"created_at":"2005-08-01T11:57:11-04:00","test":false,"authorization":"authorization-key","location_id":null,"user_id":null,"parent_id":null,"processed_at":"2005-08-01T11:57:11-04:00","device_id":null,"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","buyer_action_info":null,"credit_card_name":null,"credit_card_wallet":null,"credit_card_expiration_month":null,"credit_card_expiration_year":null,"payment_method_name":"visa"},"receipt":{"testcase":true,"authorization":"123456"},"currency_exchange_adjustment":null,"amount":"598.94","currency":"USD","authorization_expires_at":null,"extended_authorization_attributes":{},"payment_id":"#1001.1","total_unsettled_set":{"presentment_money":{"amount":"348.0","currency":"USD"},"shop_money":{"amount":"348.0","currency":"USD"}},"manual_payment_gateway":false,"admin_graphql_api_id":"gid://shopify/OrderTransaction/389404469"}}
```