The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Anchor to section titled 'undefined'

Payment

Multiple access scopes needed — refer to each endpoint for access scope requirements.

Requires access to 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 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.

Was this section helpful?
Anchor to section titled 'The Payment resource'

The Payment resource

Properties
credit_card
The details of the credit card used for payment. The following attributes are available:
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.
transaction
The details of the transaction, including the following attributes:
unique_token
A unique idempotency token generated by the app that created the payment request. For more information, refer to Idempotent requests.
Was this section helpful?
{}The Payment resource
{
  "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"
}
Anchor to section titled 'POST request, Creates a new payment'

post
Creates a new payment

Creates a payment on a checkout using the session ID returned by the card vault
Anchor to section titled 'Parameters of Creates a new payment'

Parameters

amount
required
The amount of the payment.
api_version
string
required
request_details
required
The details of the request, including the following attributes:
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.
Was this section helpful?
Anchor to section titled 'Examples of Creates a new payment'

Examples

Path parameters
token=7yjf4v2we7gamku6a6h7tvm8h3mmvs4x
string
required
Request body
payment
Learn more about accessing protected customer data
Payment resource
Was this section helpful?
post
/admin/api/2024-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json
Copy
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-e63221856e64d2df","unique_token":"client-side-idempotency-token"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2024-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}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": 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": []
    }
  }
}
Anchor to section titled 'GET request, Retrieves a single payment'

get
Retrieves a single payment

Requires checkouts access scope.

Retrieves the payment information for an existing payment
Anchor to section titled 'Parameters of Retrieves a single payment'

Parameters

api_version
string
required
payment_id
string
required
token
string
required
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a single payment'

Examples

Was this section helpful?
get
/admin/api/2024-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}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": "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": []
    }
  }
}