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 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.
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.
## Resource Properties ### Payment * credit_card: The details of the credit card used for payment. The following attributes are available:session_id stored in the vault
Request:
```
POST /admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json
{"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-e63221856e64d2df","unique_token":"client-side-idempotency-token"}}
```
Response:
```
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":2025,"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":2025,"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":"2024-09-19T10:12:29-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=1726755057","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=1726755057","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":550558813,"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":2025,"customer_id":207119551},"billing_address":{"id":550558813,"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":[]}}}
```
#### 422
Creates a new payment
Examples:
##### Creating an authorization with a valid session ID but an invalid credit card number fails and returns errors
Request:
```
POST /admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json
{"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-ccc088d2d56b8435","unique_token":"client-side-idempotency-token"}}
```
Response:
```
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
Request:
```
POST /admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json
{"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-247c19338aa49161","unique_token":"client-side-idempotency-token"}}
```
Response:
```
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
Request:
```
POST /admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json
{"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"}}
```
Response:
```
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":{}}]}}}
```
## Retrieves a single payment
Retrieves the payment information for an existing payment
### Endpoint
/admin/api/#{api_version}/checkouts/{token}/payments/{payment_id}.json (GET)
### Parameters
* api_version (required):
* payment_id (required):
* token (required):
### Responses
#### 200
Retrieves a single payment
Examples:
##### Retrieve a payment with a failed transaction
Request:
```
GET /admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json
```
Response:
```
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":"2024-09-19T10:12:17-04:00","currency":"USD","error_code":null,"parent_id":null,"gateway":"bogus","id":1068278463,"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":"2024-09-19T10:12:17-04:00","currency":"USD","error_code":null,"parent_id":null,"gateway":"bogus","id":1068278463,"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=1726755057","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=1726755057","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":550558813,"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":550558813,"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
Request:
```
GET /admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json
```
Response:
```
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":"2024-09-19T10:12:18-04:00","currency":"USD","error_code":null,"parent_id":null,"gateway":"bogus","id":1068278464,"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":"2024-09-19T10:12:18-04:00","currency":"USD","error_code":null,"parent_id":null,"gateway":"bogus","id":1068278464,"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=1726755057","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=1726755057","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":550558813,"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":550558813,"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":[]}}}
```