Payment

Version 2019-10

Note

Sales channels require elevated permissions to interact with the Payment resource. For more information, see Request payment processing.

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.

For more information about using the Payment resource, see Completing a payment.

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.

What you can do with Payment

The Shopify API lets you do the following with the Payment resource. More detailed versions of these general actions may be available:

POST https://elb.deposit.shopifycs.com/sessions Stores a credit card in the card vault
POST /admin/api/2019-10/checkouts/{token}/payments.json Creates a new payment
GET /admin/api/2019-10/checkouts/{token}/payments.json Retrieves a list of payments on a particular checkout
GET /admin/api/2019-10/checkouts/{token}/payments/{payment_id}.json Retrieves a single payment
GET /admin/api/2019-10/checkouts/{token}/payments/count.json Counts the number of payments attempted on a checkout

Payment properties

credit_card	`"credit_card": { "first_name": "Bob", "last_name": "Norman", "first_digits": "424242", "last_digits": "4242", "brand": "visa", "expiry_month": 12, "expiry_year": 2020 }` The details of the credit card used for payment. The following attributes are available: 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	`"id": 367556198456` A unique identifer for the payment generated by Shopify.
payment_processing_error_message	`"payment_processing_error_message": "Card was declined"` A message describing the error that occured when attempting to process payment, if any.
next_action	`"next_action": { "redirect_url": "https://shop-domain-url.myshopify.com/:shop_id/checkouts/:token/authentications/:auth_token/3ds" }` 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 Authenticating payments with 3D Secure.
transaction	`"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 }` The details of the transaction, including the following attributes: 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./li> test: Whether or not the transaction was a test.
unique_token	`"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.

Endpoints

POST https://elb.deposit.shopifycs.com/sessions

Stores a credit card in the card vault. Credit cards cannot be sent to the Checkout API directly. They must be sent to the card vault, which in response will return a session ID. This session ID can then be used when calling the POST #{token}/payments.json endpoint. A session ID is valid only for a single call to the endpoint. The card vault has a static URL and is located at https://elb.deposit.shopifycs.com/sessions. It is also provided via the payment_url property on the Checkout resource.

credit_card
required

The credit card used for payment. See the properties table above for a description of its attributes.

Create a payment session with the specified billing details.

POST https://elb.deposit.shopifycs.com/sessions

{
  "credit_card": {
    "number": "1",
    "first_name": "John",
    "last_name": "Smith",
    "month": "5",
    "year": "15",
    "verification_value": "123"
  }
}

View Response

HTTP/1.1 200 OK
{
  "id": "83hru3obno3hu434b3u"
}

POST /admin/api/2019-10/checkouts/{token}/payments.json

Creates a payment on a checkout using the session ID returned by the card vault

amount required	The amount of the payment.
request_details required	The details of the request, including the following attributes: 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 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.
unique_token required	A unique idempotency token generated by your app. This can be any value, but must be unique across all payment requests.

Create an authorization using a valid `session_id` stored in the vault

POST /admin/api/2019-10/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": "398.00",
    "session_id": "global-da38949580862139",
    "unique_token": "client-side-idempotency-token"
  }
}

View Response

HTTP/1.1 202 Accepted
Location: https://apple.myshopify.com/admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/1071573807.json
Retry-After: 1
{
  "payment": {
    "id": 1071573807,
    "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": 2022,
      "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,
      "email": "bob.norman@hostmail.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": "398.00",
      "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",
              "credit_card_name": null,
              "credit_card_wallet": null,
              "credit_card_expiration_month": null,
              "credit_card_expiration_year": null
            }
          },
          "credit_card": null
        },
        {
          "id": 1071573807,
          "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": 2022,
            "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": "https://apple.myshopify.com/690933842/policies/subscription-policy.html?locale=en",
      "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": "398.00",
      "total_tax": "0.00",
      "total_tip_received": "0.00",
      "total_line_items_price": "398.00",
      "updated_at": "2021-04-01T15:09:17-04:00",
      "user_id": null,
      "web_url": "https://checkout.local/690933842/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "line_items": [
        {
          "id": "2260d828d29f625d",
          "key": "2260d828d29f625d",
          "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/0006/9093/3842/products/ipod-nano.png?v=1617304047",
          "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": [],
          "tax_lines": []
        },
        {
          "id": "a5056ec7c4a94620",
          "key": "a5056ec7c4a94620",
          "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/0006/9093/3842/products/ipod-nano-2.png?v=1617304047",
          "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": [],
          "tax_lines": []
        }
      ],
      "gift_cards": [],
      "tax_lines": [],
      "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": "555-625-1199",
        "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": 2022,
        "customer_id": 207119551
      },
      "billing_address": {
        "id": 550558813,
        "first_name": "Bob",
        "last_name": "Norman",
        "phone": "555-625-1199",
        "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
    }
  }
}

Creating an authorization with a valid session ID but an invalid credit card number fails and returns errors

POST /admin/api/2019-10/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-e079f2d7da6726c8",
    "unique_token": "client-side-idempotency-token"
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "amount": [
      {
        "code": "total_price_mismatch",
        "message": "The amount of the payment must match the total of 398.00.",
        "options": {
          "amount": "398.00"
        }
      }
    ],
    "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 an invalid session ID fails and returns errors

POST /admin/api/2019-10/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"
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "amount": [
      {
        "code": "total_price_mismatch",
        "message": "The amount of the payment must match the total of 398.00.",
        "options": {
          "amount": "398.00"
        }
      }
    ],
    "payment_gateway": [
      {
        "code": "invalid",
        "message": "is invalid",
        "options": {}
      }
    ],
    "checkout": {
      "payment_gateway": [
        {
          "code": "invalid",
          "message": "is invalid",
          "options": {}
        }
      ]
    }
  }
}

Creating an authorization with a valid session can fail for various reasons

POST /admin/api/2019-10/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": "398.00",
    "session_id": "global-ca964894d3c5dcc6",
    "unique_token": "client-side-idempotency-token"
  }
}

View 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."
        }
      }
    ]
  }
}

GET /admin/api/2019-10/checkouts/{token}/payments.json

Retrieves a list of payments on a particular checkout

Retrieve all the payments on a checkout

GET /admin/api/2019-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json

View Response

HTTP/1.1 200 OK
{
  "payments": [
    {
      "id": 25428999,
      "unique_token": "e01e661f4a99acd9dcdg6f1422d0d6f7",
      "payment_processing_error_message": null,
      "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
      },
      "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,
        "email": "bob.norman@hostmail.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,
            "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
            },
            "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": "https://apple.myshopify.com/690933842/policies/subscription-policy.html?locale=en",
        "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/690933842/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
        "line_items": [
          {
            "id": "2260d828d29f625d",
            "key": "2260d828d29f625d",
            "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/0006/9093/3842/products/ipod-nano.png?v=1617304047",
            "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": [],
            "tax_lines": []
          },
          {
            "id": "a5056ec7c4a94620",
            "key": "a5056ec7c4a94620",
            "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/0006/9093/3842/products/ipod-nano-2.png?v=1617304047",
            "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": [],
            "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": "555-625-1199",
          "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": "555-625-1199",
          "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
      }
    }
  ]
}

GET /admin/api/2019-10/checkouts/{token}/payments/{payment_id}.json

Retrieves the payment information for an existing payment

Retrieve a payment with a succesful transaction

GET /admin/api/2019-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json

View Response

HTTP/1.1 200 OK
Location: https://apple.myshopify.com/admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json
{
  "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": "2021-04-01T15:10:09-04:00",
      "currency": "USD",
      "error_code": null,
      "parent_id": null,
      "gateway": "bogus",
      "id": 1072844672,
      "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,
      "email": "bob.norman@hostmail.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": "2021-04-01T15:10:09-04:00",
            "currency": "USD",
            "error_code": null,
            "parent_id": null,
            "gateway": "bogus",
            "id": 1072844672,
            "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": "https://apple.myshopify.com/690933842/policies/subscription-policy.html?locale=en",
      "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/690933842/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "line_items": [
        {
          "id": "2260d828d29f625d",
          "key": "2260d828d29f625d",
          "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/0006/9093/3842/products/ipod-nano.png?v=1617304047",
          "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": [],
          "tax_lines": []
        },
        {
          "id": "a5056ec7c4a94620",
          "key": "a5056ec7c4a94620",
          "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/0006/9093/3842/products/ipod-nano-2.png?v=1617304047",
          "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": [],
          "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": "555-625-1199",
        "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": "555-625-1199",
        "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
    }
  }
}

Retrieve a payment with a failed transaction

GET /admin/api/2019-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json

View Response

HTTP/1.1 200 OK
Location: https://apple.myshopify.com/admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json
{
  "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": "2021-04-01T15:10:18-04:00",
      "currency": "USD",
      "error_code": null,
      "parent_id": null,
      "gateway": "bogus",
      "id": 1072844673,
      "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,
      "email": "bob.norman@hostmail.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": "2021-04-01T15:10:18-04:00",
            "currency": "USD",
            "error_code": null,
            "parent_id": null,
            "gateway": "bogus",
            "id": 1072844673,
            "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": "https://apple.myshopify.com/690933842/policies/subscription-policy.html?locale=en",
      "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/690933842/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "line_items": [
        {
          "id": "2260d828d29f625d",
          "key": "2260d828d29f625d",
          "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/0006/9093/3842/products/ipod-nano.png?v=1617304047",
          "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": [],
          "tax_lines": []
        },
        {
          "id": "a5056ec7c4a94620",
          "key": "a5056ec7c4a94620",
          "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/0006/9093/3842/products/ipod-nano-2.png?v=1617304047",
          "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": [],
          "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": "555-625-1199",
        "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": "555-625-1199",
        "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
    }
  }
}

GET /admin/api/2019-10/checkouts/{token}/payments/count.json

Counts the number of payments attempted on a checkout

Retrieve the number of payments on a checkout

GET /admin/api/2019-10/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

Version 2020-01

Note

Sales channels require elevated permissions to interact with the Payment resource. For more information, see Request payment processing.

The Payment resource allows sales channels to build a fully native checkout experience by submitting a customer's payment details directly to Shopify.

For more information about using the Payment resource, see Completing a payment.

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.

What you can do with Payment

The Shopify API lets you do the following with the Payment resource. More detailed versions of these general actions may be available:

POST https://elb.deposit.shopifycs.com/sessions Stores a credit card in the card vault
POST /admin/api/2020-01/checkouts/{token}/payments.json Creates a new payment
GET /admin/api/2020-01/checkouts/{token}/payments.json Retrieves a list of payments on a particular checkout
GET /admin/api/2020-01/checkouts/{token}/payments/{payment_id}.json Retrieves a single payment
GET /admin/api/2020-01/checkouts/{token}/payments/count.json Counts the number of payments attempted on a checkout

Payment properties

credit_card	`"credit_card": { "first_name": "Bob", "last_name": "Norman", "first_digits": "424242", "last_digits": "4242", "brand": "visa", "expiry_month": 12, "expiry_year": 2020 }` The details of the credit card used for payment. The following attributes are available: 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	`"id": 367556198456` A unique identifer for the payment generated by Shopify.
payment_processing_error_message	`"payment_processing_error_message": "Card was declined"` A message describing the error that occured when attempting to process payment, if any.
next_action	`"next_action": { "redirect_url": "https://shop-domain-url.myshopify.com/:shop_id/checkouts/:token/authentications/:auth_token/3ds" }` 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 Authenticating payments with 3D Secure.
transaction	`"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 }` The details of the transaction, including the following attributes: 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./li> test: Whether or not the transaction was a test.
unique_token	`"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.

Endpoints

POST https://elb.deposit.shopifycs.com/sessions

credit_card
required

The credit card used for payment. See the properties table above for a description of its attributes.

Create a payment session with the specified billing details.

POST https://elb.deposit.shopifycs.com/sessions

{
  "credit_card": {
    "number": "1",
    "first_name": "John",
    "last_name": "Smith",
    "month": "5",
    "year": "15",
    "verification_value": "123"
  }
}

View Response

HTTP/1.1 200 OK
{
  "id": "83hru3obno3hu434b3u"
}

POST /admin/api/2020-01/checkouts/{token}/payments.json

Creates a payment on a checkout using the session ID returned by the card vault

amount required	The amount of the payment.
request_details required	The details of the request, including the following attributes: 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 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.
unique_token required	A unique idempotency token generated by your app. This can be any value, but must be unique across all payment requests.

Create an authorization using a valid `session_id` stored in the vault

POST /admin/api/2020-01/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": "398.00",
    "session_id": "global-da38949580862139",
    "unique_token": "client-side-idempotency-token"
  }
}

View Response

HTTP/1.1 202 Accepted
Location: https://apple.myshopify.com/admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/1071573807.json
Retry-After: 1
{
  "payment": {
    "id": 1071573807,
    "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": 2022,
      "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,
      "email": "bob.norman@hostmail.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": "398.00",
      "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",
              "credit_card_name": null,
              "credit_card_wallet": null,
              "credit_card_expiration_month": null,
              "credit_card_expiration_year": null
            }
          },
          "credit_card": null
        },
        {
          "id": 1071573807,
          "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": 2022,
            "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": "https://apple.myshopify.com/690933842/policies/subscription-policy.html?locale=en",
      "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": "398.00",
      "total_tax": "0.00",
      "total_tip_received": "0.00",
      "total_line_items_price": "398.00",
      "updated_at": "2021-04-01T15:09:17-04:00",
      "user_id": null,
      "web_url": "https://checkout.local/690933842/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "line_items": [
        {
          "id": "2260d828d29f625d",
          "key": "2260d828d29f625d",
          "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/0006/9093/3842/products/ipod-nano.png?v=1617304047",
          "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": [],
          "tax_lines": []
        },
        {
          "id": "a5056ec7c4a94620",
          "key": "a5056ec7c4a94620",
          "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/0006/9093/3842/products/ipod-nano-2.png?v=1617304047",
          "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": [],
          "tax_lines": []
        }
      ],
      "gift_cards": [],
      "tax_lines": [],
      "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": "555-625-1199",
        "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": 2022,
        "customer_id": 207119551
      },
      "billing_address": {
        "id": 550558813,
        "first_name": "Bob",
        "last_name": "Norman",
        "phone": "555-625-1199",
        "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
    }
  }
}

Creating an authorization with a valid session ID but an invalid credit card number fails and returns errors

POST /admin/api/2020-01/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-e079f2d7da6726c8",
    "unique_token": "client-side-idempotency-token"
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "amount": [
      {
        "code": "total_price_mismatch",
        "message": "The amount of the payment must match the total of 398.00.",
        "options": {
          "amount": "398.00"
        }
      }
    ],
    "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 an invalid session ID fails and returns errors

POST /admin/api/2020-01/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"
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "amount": [
      {
        "code": "total_price_mismatch",
        "message": "The amount of the payment must match the total of 398.00.",
        "options": {
          "amount": "398.00"
        }
      }
    ],
    "payment_gateway": [
      {
        "code": "invalid",
        "message": "is invalid",
        "options": {}
      }
    ],
    "checkout": {
      "payment_gateway": [
        {
          "code": "invalid",
          "message": "is invalid",
          "options": {}
        }
      ]
    }
  }
}

Creating an authorization with a valid session can fail for various reasons

POST /admin/api/2020-01/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": "398.00",
    "session_id": "global-ca964894d3c5dcc6",
    "unique_token": "client-side-idempotency-token"
  }
}

View 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."
        }
      }
    ]
  }
}

GET /admin/api/2020-01/checkouts/{token}/payments.json

Retrieves a list of payments on a particular checkout

Retrieve all the payments on a checkout

GET /admin/api/2020-01/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments.json

View Response

HTTP/1.1 200 OK
{
  "payments": [
    {
      "id": 25428999,
      "unique_token": "e01e661f4a99acd9dcdg6f1422d0d6f7",
      "payment_processing_error_message": null,
      "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
      },
      "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,
        "email": "bob.norman@hostmail.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,
            "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
            },
            "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": "https://apple.myshopify.com/690933842/policies/subscription-policy.html?locale=en",
        "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/690933842/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
        "line_items": [
          {
            "id": "2260d828d29f625d",
            "key": "2260d828d29f625d",
            "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/0006/9093/3842/products/ipod-nano.png?v=1617304047",
            "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": [],
            "tax_lines": []
          },
          {
            "id": "a5056ec7c4a94620",
            "key": "a5056ec7c4a94620",
            "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/0006/9093/3842/products/ipod-nano-2.png?v=1617304047",
            "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": [],
            "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": "555-625-1199",
          "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": "555-625-1199",
          "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
      }
    }
  ]
}

GET /admin/api/2020-01/checkouts/{token}/payments/{payment_id}.json

Retrieves the payment information for an existing payment

Retrieve a payment with a succesful transaction

GET /admin/api/2020-01/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json

View Response

HTTP/1.1 200 OK
Location: https://apple.myshopify.com/admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json
{
  "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": "2021-04-01T15:10:09-04:00",
      "currency": "USD",
      "error_code": null,
      "parent_id": null,
      "gateway": "bogus",
      "id": 1072844672,
      "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,
      "email": "bob.norman@hostmail.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": "2021-04-01T15:10:09-04:00",
            "currency": "USD",
            "error_code": null,
            "parent_id": null,
            "gateway": "bogus",
            "id": 1072844672,
            "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": "https://apple.myshopify.com/690933842/policies/subscription-policy.html?locale=en",
      "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/690933842/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "line_items": [
        {
          "id": "2260d828d29f625d",
          "key": "2260d828d29f625d",
          "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/0006/9093/3842/products/ipod-nano.png?v=1617304047",
          "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": [],
          "tax_lines": []
        },
        {
          "id": "a5056ec7c4a94620",
          "key": "a5056ec7c4a94620",
          "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/0006/9093/3842/products/ipod-nano-2.png?v=1617304047",
          "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": [],
          "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": "555-625-1199",
        "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": "555-625-1199",
        "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
    }
  }
}

Retrieve a payment with a failed transaction

GET /admin/api/2020-01/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json

View Response

HTTP/1.1 200 OK
Location: https://apple.myshopify.com/admin/api/unstable/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/25428999.json
{
  "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": "2021-04-01T15:10:18-04:00",
      "currency": "USD",
      "error_code": null,
      "parent_id": null,
      "gateway": "bogus",
      "id": 1072844673,
      "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,
      "email": "bob.norman@hostmail.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": "2021-04-01T15:10:18-04:00",
            "currency": "USD",
            "error_code": null,
            "parent_id": null,
            "gateway": "bogus",
            "id": 1072844673,
            "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": "https://apple.myshopify.com/690933842/policies/subscription-policy.html?locale=en",
      "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/690933842/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x",
      "line_items": [
        {
          "id": "2260d828d29f625d",
          "key": "2260d828d29f625d",
          "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/0006/9093/3842/products/ipod-nano.png?v=1617304047",
          "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": [],
          "tax_lines": []
        },
        {
          "id": "a5056ec7c4a94620",
          "key": "a5056ec7c4a94620",
          "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/0006/9093/3842/products/ipod-nano-2.png?v=1617304047",
          "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": [],
          "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": "555-625-1199",
        "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": "555-625-1199",
        "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
    }
  }
}

GET /admin/api/2020-01/checkouts/{token}/payments/count.json

Counts the number of payments attempted on a checkout

Retrieve the number of payments on a checkout

GET /admin/api/2020-01/checkouts/7yjf4v2we7gamku6a6h7tvm8h3mmvs4x/payments/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

Version 2020-04

Note

Sales channels require elevated permissions to interact with the Payment resource. For more information, see Request payment processing.

The Payment resource allows sales channels to build a fully native checkout experience by submitting a customer's payment details directly to Shopify.

For more information about using the Payment resource, see Completing a payment.

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.

What you can do with Payment

The Shopify API lets you do the following with the Payment resource. More detailed versions of these general actions may be available:

POST https://elb.deposit.shopifycs.com/sessions Stores a credit card in the card vault
POST /admin/api/2020-04/checkouts/{token}/payments.json Creates a new payment
GET /admin/api/2020-04/checkouts/{token}/payments.json Retrieves a list of payments on a particular checkout
GET /admin/api/2020-04/checkouts/{token}/payments/{payment_id}.json Retrieves a single payment
GET /admin/api/2020-04/checkouts/{token}/payments/count.json Counts the number of payments attempted on a checkout

Payment properties

credit_card	`"credit_card": { "first_name": "Bob", "last_name": "Norman", "first_digits": "424242", "last_digits": "4242", "brand": "visa", "expiry_month": 12, "expiry_year": 2020 }` The details of the credit card used for payment. The following attributes are available: 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	`"id": 367556198456` A unique identifer for the payment generated by Shopify.
payment_processing_error_message	`"payment_processing_error_message": "Card was declined"` A message describing the error that occured when attempting to process payment, if any.
next_action	`"next_action": { "redirect_url": "https://shop-domain-url.myshopify.com/:shop_id/checkouts/:token/authentications/:auth_token/3ds" }` 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 Authenticating payments with 3D Secure.
transaction	`"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 }` The details of the transaction, including the following attributes: 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./li> test: Whether or not the transaction was a test.
unique_token	`"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.

Endpoints

POST https://elb.deposit.shopifycs.com/sessions

credit_card
required

The credit card used for payment. See the properties table above for a description of its attributes.

Create a payment session with the specified billing details.

POST https://elb.deposit.shopifycs.com/sessions

{
  "credit_card": {
    "number": "1",
    "first_name": "John",
    "last_name": "Smith",
    "month": "5",
    "year": "15",
    "verification_value": "123"
  }
}

View Response

HTTP/1.1 200 OK
{
  "id": "83hru3obno3hu434b3u"
}

POST /admin/api/2020-04/checkouts/{token}/payments.json

Creates a payment on a checkout using the session ID returned by the card vault

amount required	The amount of the payment.
request_details required	The details of the request, including the following attributes: 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 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.
unique_token required	A unique idempotency token generated by your app. This can be any value, but must be unique across all payment requests.

Create an authorization using a valid `session_id` stored in the vault

POST /admin/api/2020-04/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": "398.00",
    "session_id": "global-da38949580862139",
    "unique_token"<

Payment

Note

What you can do with Payment

Payment properties

Endpoints

Create a payment session with the specified billing details.

Create an authorization using a valid session_id stored in the vault

Creating an authorization with a valid session ID but an invalid credit card number fails and returns errors

Creating an authorization with an invalid session ID fails and returns errors

Creating an authorization with a valid session can fail for various reasons

Retrieve all the payments on a checkout

Retrieve a payment with a succesful transaction

Retrieve a payment with a failed transaction

Retrieve the number of payments on a checkout

Note

What you can do with Payment

Payment properties

Endpoints

Create a payment session with the specified billing details.

Create an authorization using a valid session_id stored in the vault

Creating an authorization with a valid session ID but an invalid credit card number fails and returns errors

Creating an authorization with an invalid session ID fails and returns errors

Creating an authorization with a valid session can fail for various reasons

Retrieve all the payments on a checkout

Retrieve a payment with a succesful transaction

Retrieve a payment with a failed transaction

Retrieve the number of payments on a checkout

Note

What you can do with Payment

Payment properties

Endpoints

Create a payment session with the specified billing details.

Create an authorization using a valid session_id stored in the vault

Create an authorization using a valid `session_id` stored in the vault

Create an authorization using a valid `session_id` stored in the vault

Create an authorization using a valid `session_id` stored in the vault