--- title: Payment description: Create and update payments to provide a custom checkout experience for your sales channel. api_version: 2025-10 api_name: admin-rest api_type: rest source_url: html: https://shopify.dev/docs/api/admin-rest/latest/resources/payment md: https://shopify.dev/docs/api/admin-rest/latest/resources/payment.md --- ![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg) The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql). For details and migration steps, visit our [migration guide](https://shopify.dev/docs/apps/build/graphql/migrate). # Payment Multiple access scopes needed — refer to each endpoint for access scope requirements. Requires access to [protected customer data](https://shopify.dev/apps/store/data-protection/protected-customer-data). Note Sales channels require elevated permissions to interact with the Payment resource. For more information, see the *Request Payment Processing* section on the [Start building a sales channel app](https://shopify.dev/apps/channels/getting-started) page. The Payment resource allows sales channels to build a fully native checkout experience by submitting a customer's payment details directly to Shopify. To complete a payment using the Payment resource, first create a payment session by submitting the card details to Shopify's card vault in exchange for a session ID. The session ID can then be used to create a payment for an existing [Checkout](https://shopify.dev/docs/admin-api/rest/reference/sales-channels/checkout). The Payment resource is compatible only with direct payment gateways. For a list of all supported payment gateways, see [*Direct and external credit card payment providers*](https://help.shopify.com/manual/payments/third-party-providers/direct-and-external-providers). \# ## Endpoints * [post](https://shopify.dev/docs/api/admin-rest/latest/resources/payment#post-checkouts-token-payments) [/admin/api/latest/checkouts/{token}/payments.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/payment#post-checkouts-token-payments) Creates a new payment * [get](https://shopify.dev/docs/api/admin-rest/latest/resources/payment#get-checkouts-token-payments-payment-id) [/admin/api/latest/checkouts/{token}/payments/{payment\_​id}.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/payment#get-checkouts-token-payments-payment-id) Retrieves a single payment *** ## The Payment resource ### Properties *** credit\_card The details of the credit card used for payment. The following attributes are available: Show credit\_card properties * **first\_name:** The first name of the cardholder. * **last\_name:** The last name of the cardholder. * **first\_digits:** The first six digits of the credit card. * **last\_digits:** The last four digits of the credit card. * **brand:** The credit card brand. * **expiry\_month:** The expiry month of the credit card. * **expiry\_year:** The expiry year of the credit card. *** id A unique identifer for the payment generated by Shopify. *** payment\_processing\_error\_message A message describing the error that occured when attempting to process payment, if any. *** next\_action Specifies the URL that your app or sales channel needs to send the customer to so that they can authenticate their payment. To learn more about how to use this property, refer to [*Payments apps overview*](https://shopify.dev/apps/payments). *** transaction The details of the transaction, including the following attributes: Show transaction properties * **amount:** The amount of the transaction. * **amount\_in:** The amount in before rounding is applied. Not applicable to credit card payments. * **amount\_out:** The amount out after rounding is applied. Not applicable to credit card payments. * **amount\_rounding:** The amount of rounding applied. Not applicable to credit card payments. * **authorization:** The authorization code returned by the payment provider. * **created\_at:** The date and time when the transaction was created. * **currency:** The currency of the transaction. * **error\_code:** The error code returned by the payment provider, if any. * **gateway:** The name of the payment provider which processed the transaction. * **id:** The unique identifier of the transaction. * **kind:** The kind of transaction processed, either *authorization* or *sale*. * **message:** The message returned by the payment provider, if any. * **status:** The status of the transaction, either *success* or *failure*. * **test:** Whether or not the transaction was a test. *** unique\_token A unique idempotency token generated by the app that created the payment request. For more information, refer to [Idempotent requests](https://shopify.dev/docs/api/admin-rest/usage/idempotent-requests). *** {} ## The Payment resource ```json { "credit_card": { "first_name": "Bob", "last_name": "Norman", "first_digits": "424242", "last_digits": "4242", "brand": "visa", "expiry_month": 12, "expiry_year": 2020 }, "id": 367556198456, "payment_processing_error_message": "Card was declined", "next_action": { "redirect_url": "https://shop-domain-url.myshopify.com/:shop_id/checkouts/:token/authentications/:auth_token/3ds" }, "transaction": { "amount": "323.17", "amount_in": null, "amount_out": null, "amount_rounding": null, "authorization": "ch_1CfBrOCNqnO8CNQxAtf5k9iX", "created_at": "2018-06-20T15:20:53-04:00", "currency": "USD", "error_code": null, "gateway": "shopify_payments", "id": 597850423352, "kind": "sale", "message": "Transaction approved", "status": "success", "test": true }, "unique_token": "client-side-idempotency-token" } ``` *** ## postCreates a new payment Creates a payment on a checkout using the session ID returned by the card vault ### Parameters *** amount required The amount of the payment. *** api\_version string required *** request\_details required The details of the request, including the following attributes: Show request\_details properties * **ip\_address**: The IP address of the customer. * **accept\_language**: The language preferences of the customer, in the same format as a standard [Accept-Language](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4) request header. * **user\_agent**: The user agent string for the customer's device. *** session\_id required A session ID provided by the card vault when creating a payment session. *** token string required *** unique\_token required A unique idempotency token generated by your app. This can be any value, but must be unique across all payment requests. *** ### Examples Create an authorization using a valid `session_id` stored in the vault Path parameters token=​7yjf4v2we7gamku6a6h7tvm8h3mmvs4x string required Request body payment​[](https://shopify.dev/apps/store/data-protection/protected-customer-data) Payment resource Show payment properties payment.unique\_​token:​"client-side-idempotency-token" A unique idempotency token generated by the app that created the payment request. For more information, refer to [Idempotent requests](https://shopify.dev/docs/api/admin-rest/usage/idempotent-requests). Creating an authorization with a valid session ID but an invalid credit card number fails and returns errors Path parameters token=​7yjf4v2we7gamku6a6h7tvm8h3mmvs4x string required Request body payment​[](https://shopify.dev/apps/store/data-protection/protected-customer-data) Payment resource Show payment properties payment.unique\_​token:​"client-side-idempotency-token" A unique idempotency token generated by the app that created the payment request. For more information, refer to [Idempotent requests](https://shopify.dev/docs/api/admin-rest/usage/idempotent-requests). Creating an authorization with a valid session can fail for various reasons Path parameters token=​7yjf4v2we7gamku6a6h7tvm8h3mmvs4x string required Request body payment​[](https://shopify.dev/apps/store/data-protection/protected-customer-data) Payment resource Show payment properties payment.unique\_​token:​"client-side-idempotency-token" A unique idempotency token generated by the app that created the payment request. For more information, refer to [Idempotent requests](https://shopify.dev/docs/api/admin-rest/usage/idempotent-requests). Creating an authorization with an invalid session ID fails and returns errors Path parameters token=​7yjf4v2we7gamku6a6h7tvm8h3mmvs4x string required Request body payment​[](https://shopify.dev/apps/store/data-protection/protected-customer-data) Payment resource Show payment properties payment.unique\_​token:​"client-side-idempotency-token" A unique idempotency token generated by the app that created the payment request. For more information, refer to [Idempotent requests](https://shopify.dev/docs/api/admin-rest/usage/idempotent-requests). post ## /admin/api/2025-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.​json ```bash curl -d '{"payment":{"request_details":{"ip_address":"123.1.1.1","accept_language":"en-US,en;q=0.8,fr;q=0.6","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"},"amount":"421.88","session_id":"global-d7b0ffbc2e7d8bf2","unique_token":"client-side-idempotency-token"}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` {} ## Response JSON ```json HTTP/1.1 202 Accepted { "payment": { "id": 1071573808, "unique_token": "client-side-idempotency-token", "payment_processing_error_message": null, "next_action": { "redirect_url": null }, "fraudulent": false, "transaction": null, "credit_card": { "first_name": "Bob", "last_name": "Norman", "first_digits": "424242", "last_digits": "4242", "brand": "bogus", "expiry_month": 9, "expiry_year": 2026, "customer_id": 207119551 }, "checkout": { "completed_at": null, "created_at": "2012-10-12T07:05:27-04:00", "currency": "USD", "presentment_currency": "USD", "customer_id": 207119551, "customer_locale": "en", "device_id": null, "discount_code": null, "discount_codes": [], "email": "bob.norman@mail.example.com", "legal_notice_url": null, "location_id": null, "name": "#446514532", "note": "", ``` ### examples * #### Create an authorization using a valid \session\_id\ stored in the vault ##### ```curl curl -d '{"payment":{"request_details":{"ip_address":"123.1.1.1","accept_language":"en-US,en;q=0.8,fr;q=0.6","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"},"amount":"421.88","session_id":"global-d7b0ffbc2e7d8bf2","unique_token":"client-side-idempotency-token"}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` ##### ```remix const { admin, session } = await authenticate.admin(request); const payment = new admin.rest.resources.Payment({session: session}); payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x"; payment.request_details = { "ip_address": "123.1.1.1", "accept_language": "en-US,en;q=0.8,fr;q=0.6", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" }; payment.amount = "421.88"; payment.session_id = "global-d7b0ffbc2e7d8bf2"; payment.unique_token = "client-side-idempotency-token"; await payment.save({ update: true, }); ``` ##### ```ruby # Session is activated via Authentication test_session = ShopifyAPI::Context.active_session payment = ShopifyAPI::Payment.new(session: test_session) payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x" payment.request_details = { "ip_address" => "123.1.1.1", "accept_language" => "en-US,en;q=0.8,fr;q=0.6", "user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" } payment.amount = "421.88" payment.session_id = "global-d7b0ffbc2e7d8bf2" payment.unique_token = "client-side-idempotency-token" payment.save! ``` ##### ```node // Session is built by the OAuth process const payment = new shopify.rest.Payment({session: session}); payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x"; payment.request_details = { "ip_address": "123.1.1.1", "accept_language": "en-US,en;q=0.8,fr;q=0.6", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" }; payment.amount = "421.88"; payment.session_id = "global-d7b0ffbc2e7d8bf2"; payment.unique_token = "client-side-idempotency-token"; await payment.save({ update: true, }); ``` #### response ```json HTTP/1.1 202 Accepted{"payment":{"id":1071573808,"unique_token":"client-side-idempotency-token","payment_processing_error_message":null,"next_action":{"redirect_url":null},"fraudulent":false,"transaction":null,"credit_card":{"first_name":"Bob","last_name":"Norman","first_digits":"424242","last_digits":"4242","brand":"bogus","expiry_month":9,"expiry_year":2026,"customer_id":207119551},"checkout":{"completed_at":null,"created_at":"2012-10-12T07:05:27-04:00","currency":"USD","presentment_currency":"USD","customer_id":207119551,"customer_locale":"en","device_id":null,"discount_code":null,"discount_codes":[],"email":"bob.norman@mail.example.com","legal_notice_url":null,"location_id":null,"name":"#446514532","note":"","note_attributes":{"custom engraving":"Happy Birthday","colour":"green"},"order_id":null,"order_status_url":null,"order":null,"payment_due":"421.88","payment_url":"https://app.local/cardserver/sessions","payments":[{"id":25428999,"unique_token":"e01e661f4a99acd9dcdg6f1422d0d6f7","payment_processing_error_message":null,"fraudulent":false,"transaction":{"amount":"598.94","amount_in":null,"amount_out":null,"amount_rounding":null,"authorization":"authorization-key","created_at":"2005-08-01T11:57:11-04:00","currency":"USD","error_code":null,"parent_id":null,"gateway":"bogus","id":389404469,"kind":"authorization","message":null,"status":"success","test":false,"receipt":{"testcase":true,"authorization":"123456"},"location_id":null,"user_id":null,"transaction_group_id":null,"device_id":null,"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"}},"credit_card":null},{"id":1071573808,"unique_token":"client-side-idempotency-token","payment_processing_error_message":null,"fraudulent":false,"transaction":null,"credit_card":{"first_name":"Bob","last_name":"Norman","first_digits":"424242","last_digits":"4242","brand":"bogus","expiry_month":9,"expiry_year":2026,"customer_id":207119551}}],"phone":null,"shopify_payments_account_id":null,"privacy_policy_url":null,"refund_policy_url":null,"requires_shipping":true,"reservation_time_left":0,"reservation_time":null,"source_identifier":null,"source_name":"web","source_url":null,"subscription_policy_url":null,"subtotal_price":"398.00","shipping_policy_url":null,"tax_exempt":false,"taxes_included":false,"terms_of_sale_url":null,"terms_of_service_url":null,"token":"7yjf4v2we7gamku6a6h7tvm8h3mmvs4x","total_price":"421.88","total_tax":"23.88","total_tip_received":"0.00","total_line_items_price":"398.00","updated_at":"2025-10-01T14:56:42-04:00","user_id":null,"web_url":"https://checkout.local/548380009/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x","total_duties":null,"total_additional_fees":null,"line_items":[{"id":"60715a3461f5f853","key":"60715a3461f5f853","product_id":632910392,"variant_id":49148385,"sku":"IPOD2008RED","vendor":"Apple","title":"IPod Nano - 8GB","variant_title":"Red","image_url":"https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano.png?v=1759343456","taxable":true,"requires_shipping":true,"gift_card":false,"price":"199.00","compare_at_price":null,"line_price":"199.00","properties":{},"quantity":1,"grams":200,"fulfillment_service":"manual","applied_discounts":[],"discount_allocations":[],"tax_lines":[{"price":"11.94","rate":0.06,"title":"Tax","channel_liable":false}]},{"id":"0703986f986628ba","key":"0703986f986628ba","product_id":632910392,"variant_id":808950810,"sku":"IPOD2008PINK","vendor":"Apple","title":"IPod Nano - 8GB","variant_title":"Pink","image_url":"https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano-2.png?v=1759343456","taxable":true,"requires_shipping":true,"gift_card":false,"price":"199.00","compare_at_price":null,"line_price":"199.00","properties":{},"quantity":1,"grams":200,"fulfillment_service":"manual","applied_discounts":[],"discount_allocations":[],"tax_lines":[{"price":"11.94","rate":0.06,"title":"Tax","channel_liable":false}]}],"gift_cards":[],"tax_lines":[{"price":"23.88","rate":0.06,"title":"Tax","compare_at":0.06}],"tax_manipulations":[],"shipping_line":{"handle":"shopify-Free%20Shipping-0.00","price":"0.00","title":"Free Shipping","tax_lines":[]},"shipping_rate":{"id":"shopify-Free%20Shipping-0.00","price":"0.00","title":"Free Shipping"},"shipping_address":{"id":921093900,"first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","company":null,"address1":"Chestnut Street 92","address2":"","city":"Louisville","province":"Kentucky","province_code":"KY","country":"United States","country_code":"US","zip":"40202"},"credit_card":{"first_name":"Bob","last_name":"Norman","first_digits":"424242","last_digits":"4242","brand":"bogus","expiry_month":9,"expiry_year":2026,"customer_id":207119551},"billing_address":{"id":921093900,"first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","company":null,"address1":"Chestnut Street 92","address2":"","city":"Louisville","province":"Kentucky","province_code":"KY","country":"United States","country_code":"US","zip":"40202"},"applied_discount":null,"applied_discounts":[],"discount_violations":[]}}} ``` * #### Creating an authorization with a valid session ID but an invalid credit card number fails and returns errors ##### ```curl curl -d '{"payment":{"request_details":{"ip_address":"123.1.1.1","accept_language":"en-US,en;q=0.8,fr;q=0.6","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"},"amount":"419.49","session_id":"global-e61392e621a235ca","unique_token":"client-side-idempotency-token"}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` ##### ```remix const { admin, session } = await authenticate.admin(request); const payment = new admin.rest.resources.Payment({session: session}); payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x"; payment.request_details = { "ip_address": "123.1.1.1", "accept_language": "en-US,en;q=0.8,fr;q=0.6", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" }; payment.amount = "419.49"; payment.session_id = "global-e61392e621a235ca"; payment.unique_token = "client-side-idempotency-token"; await payment.save({ update: true, }); ``` ##### ```ruby # Session is activated via Authentication test_session = ShopifyAPI::Context.active_session payment = ShopifyAPI::Payment.new(session: test_session) payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x" payment.request_details = { "ip_address" => "123.1.1.1", "accept_language" => "en-US,en;q=0.8,fr;q=0.6", "user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" } payment.amount = "419.49" payment.session_id = "global-e61392e621a235ca" payment.unique_token = "client-side-idempotency-token" payment.save! ``` ##### ```node // Session is built by the OAuth process const payment = new shopify.rest.Payment({session: session}); payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x"; payment.request_details = { "ip_address": "123.1.1.1", "accept_language": "en-US,en;q=0.8,fr;q=0.6", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" }; payment.amount = "419.49"; payment.session_id = "global-e61392e621a235ca"; payment.unique_token = "client-side-idempotency-token"; await payment.save({ update: true, }); ``` #### response ```json HTTP/1.1 422 Unprocessable Entity{"errors":{"amount":[{"code":"total_price_mismatch","message":"The amount of the payment must match the total of 421.88.","options":{"amount":"421.88"}}],"credit_card":{"brand":[{"code":"invalid","message":"is invalid","options":{}}],"number":[{"code":"invalid","message":"is invalid","options":{}}]},"checkout":{"credit_card":{"brand":[{"code":"invalid","message":"is invalid","options":{}}],"number":[{"code":"invalid","message":"is invalid","options":{}}]}}}} ``` * #### Creating an authorization with a valid session can fail for various reasons ##### ```curl curl -d '{"payment":{"request_details":{"ip_address":"123.1.1.1","accept_language":"en-US,en;q=0.8,fr;q=0.6","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"},"amount":"421.88","session_id":"global-ae74f382838e717a","unique_token":"client-side-idempotency-token"}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` ##### ```remix const { admin, session } = await authenticate.admin(request); const payment = new admin.rest.resources.Payment({session: session}); payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x"; payment.request_details = { "ip_address": "123.1.1.1", "accept_language": "en-US,en;q=0.8,fr;q=0.6", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" }; payment.amount = "421.88"; payment.session_id = "global-ae74f382838e717a"; payment.unique_token = "client-side-idempotency-token"; await payment.save({ update: true, }); ``` ##### ```ruby # Session is activated via Authentication test_session = ShopifyAPI::Context.active_session payment = ShopifyAPI::Payment.new(session: test_session) payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x" payment.request_details = { "ip_address" => "123.1.1.1", "accept_language" => "en-US,en;q=0.8,fr;q=0.6", "user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" } payment.amount = "421.88" payment.session_id = "global-ae74f382838e717a" payment.unique_token = "client-side-idempotency-token" payment.save! ``` ##### ```node // Session is built by the OAuth process const payment = new shopify.rest.Payment({session: session}); payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x"; payment.request_details = { "ip_address": "123.1.1.1", "accept_language": "en-US,en;q=0.8,fr;q=0.6", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" }; payment.amount = "421.88"; payment.session_id = "global-ae74f382838e717a"; payment.unique_token = "client-side-idempotency-token"; await payment.save({ update: true, }); ``` #### response ```json HTTP/1.1 422 Unprocessable Entity{"errors":{"base":[{"code":"processing_error","message":"Your payment could not be processed at this time, please try again in a few minutes","options":{"raw_gateway_error":"Service is unavailable."}}]}} ``` * #### Creating an authorization with an invalid session ID fails and returns errors ##### ```curl curl -d '{"payment":{"request_details":{"ip_address":"123.1.1.1","accept_language":"en-US,en;q=0.8,fr;q=0.6","user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"},"amount":"419.49","session_id":"global-an_invalid_session_id","unique_token":"client-side-idempotency-token"}}' \ -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json" \ -H "X-Shopify-Access-Token: {access_token}" \ -H "Content-Type: application/json" ``` ##### ```remix const { admin, session } = await authenticate.admin(request); const payment = new admin.rest.resources.Payment({session: session}); payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x"; payment.request_details = { "ip_address": "123.1.1.1", "accept_language": "en-US,en;q=0.8,fr;q=0.6", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" }; payment.amount = "419.49"; payment.session_id = "global-an_invalid_session_id"; payment.unique_token = "client-side-idempotency-token"; await payment.save({ update: true, }); ``` ##### ```ruby # Session is activated via Authentication test_session = ShopifyAPI::Context.active_session payment = ShopifyAPI::Payment.new(session: test_session) payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x" payment.request_details = { "ip_address" => "123.1.1.1", "accept_language" => "en-US,en;q=0.8,fr;q=0.6", "user_agent" => "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" } payment.amount = "419.49" payment.session_id = "global-an_invalid_session_id" payment.unique_token = "client-side-idempotency-token" payment.save! ``` ##### ```node // Session is built by the OAuth process const payment = new shopify.rest.Payment({session: session}); payment.checkout_id = "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x"; payment.request_details = { "ip_address": "123.1.1.1", "accept_language": "en-US,en;q=0.8,fr;q=0.6", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36" }; payment.amount = "419.49"; payment.session_id = "global-an_invalid_session_id"; payment.unique_token = "client-side-idempotency-token"; await payment.save({ update: true, }); ``` #### response ```json HTTP/1.1 422 Unprocessable Entity{"errors":{"amount":[{"code":"total_price_mismatch","message":"The amount of the payment must match the total of 421.88.","options":{"amount":"421.88"}}],"payment_gateway":[{"code":"invalid","message":"is invalid","options":{}}],"checkout":{"payment_gateway":[{"code":"invalid","message":"is invalid","options":{}}]}}} ``` *** ## getRetrieves a single payment Requires `checkouts` access scope. Retrieves the payment information for an existing payment ### Parameters *** api\_version string required *** payment\_id string required *** token string required *** ### Examples Retrieve a payment with a failed transaction Retrieve a payment with a succesful transaction get ## /admin/api/2025-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.​json ```bash curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` {} ## Response JSON ```json HTTP/1.1 200 OK { "payment": { "id": 25428999, "unique_token": "e01e661f4a99acd9dcdg6f1422d0d6f7", "payment_processing_error_message": null, "next_action": { "redirect_url": null }, "fraudulent": false, "transaction": { "amount": "419.49", "amount_in": null, "amount_out": null, "amount_rounding": null, "authorization": null, "created_at": "2025-10-01T14:56:45-04:00", "currency": "USD", "error_code": null, "parent_id": null, "gateway": "bogus", "id": 1068278468, "kind": "authorization", "message": null, "status": "failure", "test": false, "receipt": {}, "location_id": null, "user_id": null, "transaction_group_id": null, "device_id": null, "payment_details": null }, "credit_card": null, "checkout": { "completed_at": null, ``` ### examples * #### Retrieve a payment with a failed transaction ##### ```curl curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` ##### ```remix await admin.rest.resources.Payment.find({ session: session, checkout_id: "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x", id: 25428999, }); ``` ##### ```ruby # Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Payment.find( session: test_session, checkout_id: "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x", id: 25428999, ) ``` ##### ```node // Session is built by the OAuth process await shopify.rest.Payment.find({ session: session, checkout_id: "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x", id: 25428999, }); ``` #### response ```json HTTP/1.1 200 OK{"payment":{"id":25428999,"unique_token":"e01e661f4a99acd9dcdg6f1422d0d6f7","payment_processing_error_message":null,"next_action":{"redirect_url":null},"fraudulent":false,"transaction":{"amount":"419.49","amount_in":null,"amount_out":null,"amount_rounding":null,"authorization":null,"created_at":"2025-10-01T14:56:45-04:00","currency":"USD","error_code":null,"parent_id":null,"gateway":"bogus","id":1068278468,"kind":"authorization","message":null,"status":"failure","test":false,"receipt":{},"location_id":null,"user_id":null,"transaction_group_id":null,"device_id":null,"payment_details":null},"credit_card":null,"checkout":{"completed_at":null,"created_at":"2012-10-12T07:05:27-04:00","currency":"USD","presentment_currency":"USD","customer_id":207119551,"customer_locale":"en","device_id":null,"discount_code":null,"discount_codes":[],"email":"bob.norman@mail.example.com","legal_notice_url":null,"location_id":null,"name":"#446514532","note":"","note_attributes":{"custom engraving":"Happy Birthday","colour":"green"},"order_id":null,"order_status_url":null,"order":null,"payment_due":"419.49","payment_url":"https://app.local/cardserver/sessions","payments":[{"id":25428999,"unique_token":"e01e661f4a99acd9dcdg6f1422d0d6f7","payment_processing_error_message":null,"fraudulent":false,"transaction":{"amount":"419.49","amount_in":null,"amount_out":null,"amount_rounding":null,"authorization":null,"created_at":"2025-10-01T14:56:45-04:00","currency":"USD","error_code":null,"parent_id":null,"gateway":"bogus","id":1068278468,"kind":"authorization","message":null,"status":"failure","test":false,"receipt":{},"location_id":null,"user_id":null,"transaction_group_id":null,"device_id":null,"payment_details":null},"credit_card":null}],"phone":null,"shopify_payments_account_id":null,"privacy_policy_url":null,"refund_policy_url":null,"requires_shipping":true,"reservation_time_left":0,"reservation_time":null,"source_identifier":null,"source_name":"web","source_url":null,"subscription_policy_url":null,"subtotal_price":"398.00","shipping_policy_url":null,"tax_exempt":false,"taxes_included":false,"terms_of_sale_url":null,"terms_of_service_url":null,"token":"7yjf4v2we7gamku6a6h7tvm8h3mmvs4x","total_price":"419.49","total_tax":"21.49","total_tip_received":"0.00","total_line_items_price":"398.00","updated_at":"2012-10-12T07:05:27-04:00","user_id":null,"web_url":"https://checkout.local/548380009/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x","total_duties":null,"total_additional_fees":null,"line_items":[{"id":"60715a3461f5f853","key":"60715a3461f5f853","product_id":632910392,"variant_id":49148385,"sku":"IPOD2008RED","vendor":"Apple","title":"IPod Nano - 8GB","variant_title":"Red","image_url":"https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano.png?v=1759343456","taxable":true,"requires_shipping":true,"gift_card":false,"price":"199.00","compare_at_price":null,"line_price":"199.00","properties":{},"quantity":1,"grams":200,"fulfillment_service":"manual","applied_discounts":[],"discount_allocations":[],"tax_lines":[]},{"id":"0703986f986628ba","key":"0703986f986628ba","product_id":632910392,"variant_id":808950810,"sku":"IPOD2008PINK","vendor":"Apple","title":"IPod Nano - 8GB","variant_title":"Pink","image_url":"https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano-2.png?v=1759343456","taxable":true,"requires_shipping":true,"gift_card":false,"price":"199.00","compare_at_price":null,"line_price":"199.00","properties":{},"quantity":1,"grams":200,"fulfillment_service":"manual","applied_discounts":[],"discount_allocations":[],"tax_lines":[]}],"gift_cards":[],"tax_lines":[{"price":"21.49","rate":0.06,"title":"State Tax","compare_at":0.06}],"tax_manipulations":[],"shipping_line":{"handle":"shopify-Free%20Shipping-0.00","price":"0.00","title":"Free Shipping","tax_lines":[]},"shipping_rate":{"id":"shopify-Free%20Shipping-0.00","price":"0.00","title":"Free Shipping"},"shipping_address":{"id":921093900,"first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","company":null,"address1":"Chestnut Street 92","address2":"","city":"Louisville","province":"Kentucky","province_code":"KY","country":"United States","country_code":"US","zip":"40202"},"credit_card":{"first_name":"Bob","last_name":"Norman","first_digits":"1","last_digits":"1","brand":"bogus","expiry_month":8,"expiry_year":2042,"customer_id":null},"billing_address":{"id":921093900,"first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","company":null,"address1":"Chestnut Street 92","address2":"","city":"Louisville","province":"Kentucky","province_code":"KY","country":"United States","country_code":"US","zip":"40202"},"applied_discount":null,"applied_discounts":[],"discount_violations":[]}}} ``` * #### Retrieve a payment with a succesful transaction ##### ```curl curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json" \ -H "X-Shopify-Access-Token: {access_token}" ``` ##### ```remix await admin.rest.resources.Payment.find({ session: session, checkout_id: "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x", id: 25428999, }); ``` ##### ```ruby # Session is activated via Authentication test_session = ShopifyAPI::Context.active_session ShopifyAPI::Payment.find( session: test_session, checkout_id: "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x", id: 25428999, ) ``` ##### ```node // Session is built by the OAuth process await shopify.rest.Payment.find({ session: session, checkout_id: "7yjf4v2we7gamku6a6h7tvm8h3mmvs4x", id: 25428999, }); ``` #### response ```json HTTP/1.1 200 OK{"payment":{"id":25428999,"unique_token":"e01e661f4a99acd9dcdg6f1422d0d6f7","payment_processing_error_message":null,"next_action":{"redirect_url":null},"fraudulent":false,"transaction":{"amount":"419.49","amount_in":null,"amount_out":null,"amount_rounding":null,"authorization":null,"created_at":"2025-10-01T14:56:39-04:00","currency":"USD","error_code":null,"parent_id":null,"gateway":"bogus","id":1068278467,"kind":"authorization","message":null,"status":"success","test":false,"receipt":{},"location_id":null,"user_id":null,"transaction_group_id":null,"device_id":null,"payment_details":null},"credit_card":null,"checkout":{"completed_at":null,"created_at":"2012-10-12T07:05:27-04:00","currency":"USD","presentment_currency":"USD","customer_id":207119551,"customer_locale":"en","device_id":null,"discount_code":null,"discount_codes":[],"email":"bob.norman@mail.example.com","legal_notice_url":null,"location_id":null,"name":"#446514532","note":"","note_attributes":{"custom engraving":"Happy Birthday","colour":"green"},"order_id":null,"order_status_url":null,"order":null,"payment_due":"419.49","payment_url":"https://app.local/cardserver/sessions","payments":[{"id":25428999,"unique_token":"e01e661f4a99acd9dcdg6f1422d0d6f7","payment_processing_error_message":null,"fraudulent":false,"transaction":{"amount":"419.49","amount_in":null,"amount_out":null,"amount_rounding":null,"authorization":null,"created_at":"2025-10-01T14:56:39-04:00","currency":"USD","error_code":null,"parent_id":null,"gateway":"bogus","id":1068278467,"kind":"authorization","message":null,"status":"success","test":false,"receipt":{},"location_id":null,"user_id":null,"transaction_group_id":null,"device_id":null,"payment_details":null},"credit_card":null}],"phone":null,"shopify_payments_account_id":null,"privacy_policy_url":null,"refund_policy_url":null,"requires_shipping":true,"reservation_time_left":0,"reservation_time":null,"source_identifier":null,"source_name":"web","source_url":null,"subscription_policy_url":null,"subtotal_price":"398.00","shipping_policy_url":null,"tax_exempt":false,"taxes_included":false,"terms_of_sale_url":null,"terms_of_service_url":null,"token":"7yjf4v2we7gamku6a6h7tvm8h3mmvs4x","total_price":"419.49","total_tax":"21.49","total_tip_received":"0.00","total_line_items_price":"398.00","updated_at":"2012-10-12T07:05:27-04:00","user_id":null,"web_url":"https://checkout.local/548380009/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x","total_duties":null,"total_additional_fees":null,"line_items":[{"id":"60715a3461f5f853","key":"60715a3461f5f853","product_id":632910392,"variant_id":49148385,"sku":"IPOD2008RED","vendor":"Apple","title":"IPod Nano - 8GB","variant_title":"Red","image_url":"https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano.png?v=1759343456","taxable":true,"requires_shipping":true,"gift_card":false,"price":"199.00","compare_at_price":null,"line_price":"199.00","properties":{},"quantity":1,"grams":200,"fulfillment_service":"manual","applied_discounts":[],"discount_allocations":[],"tax_lines":[]},{"id":"0703986f986628ba","key":"0703986f986628ba","product_id":632910392,"variant_id":808950810,"sku":"IPOD2008PINK","vendor":"Apple","title":"IPod Nano - 8GB","variant_title":"Pink","image_url":"https://cdn.shopify.com/s/files/1/0005/4838/0009/products/ipod-nano-2.png?v=1759343456","taxable":true,"requires_shipping":true,"gift_card":false,"price":"199.00","compare_at_price":null,"line_price":"199.00","properties":{},"quantity":1,"grams":200,"fulfillment_service":"manual","applied_discounts":[],"discount_allocations":[],"tax_lines":[]}],"gift_cards":[],"tax_lines":[{"price":"21.49","rate":0.06,"title":"State Tax","compare_at":0.06}],"tax_manipulations":[],"shipping_line":{"handle":"shopify-Free%20Shipping-0.00","price":"0.00","title":"Free Shipping","tax_lines":[]},"shipping_rate":{"id":"shopify-Free%20Shipping-0.00","price":"0.00","title":"Free Shipping"},"shipping_address":{"id":921093900,"first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","company":null,"address1":"Chestnut Street 92","address2":"","city":"Louisville","province":"Kentucky","province_code":"KY","country":"United States","country_code":"US","zip":"40202"},"credit_card":{"first_name":"Bob","last_name":"Norman","first_digits":"1","last_digits":"1","brand":"bogus","expiry_month":8,"expiry_year":2042,"customer_id":null},"billing_address":{"id":921093900,"first_name":"Bob","last_name":"Norman","phone":"+1(502)-459-2181","company":null,"address1":"Chestnut Street 92","address2":"","city":"Louisville","province":"Kentucky","province_code":"KY","country":"United States","country_code":"US","zip":"40202"},"applied_discount":null,"applied_discounts":[],"discount_violations":[]}}} ```