Amazon Pay for Magento 2 GraphQL Documentation

GraphQL Queries, Mutations, and Types for the Amazon Pay Checkout Session API

API Endpoints

A sample GraphQL endpoint on a Magento installation:
https://example-site.com/graphql

Queries

`checkoutSessionConfig`

The config values needed for rendering the Amazon Pay Button.

Returns a CheckoutSessionConfigOutput

Name	Description
`cartId` - `String`

Example

Query

query checkoutSessionConfig($cartId: String) {
  checkoutSessionConfig(cartId: $cartId) {
    button_color
    checkout_payload
    checkout_signature
    currency
    sandbox
    language
    login_payload
    login_signature
    merchant_id
    pay_only
    paynow_payload
    paynow_signature
    public_key_id
  }
}

Variables

{
  "cartId": "d7Vw50EfbxdhgnoehD8ytqX8VM8nJL28"
}

Response

{
  "data": {
    "checkoutSessionConfig": {
      "button_color": "Gold",
      "checkout_payload": "{\"webCheckoutDetails\":{\"checkoutReviewReturnUrl\":\"https://example-site.com/amazon_pay/login/checkout/\",\"checkoutCancelUrl\":\"https://example-site.com/\"},\"storeId\":\"amzn1.application-oa2-client.6df660f2573c40e8ba5815b43b8434da\"}",
      "checkout_signature": "BX/MOkF6pzmOp+PnznSPNmO9UdUCl3m7sRX92KJZOwlalKwfRx+AMDsG3T/LvGONe4MTkNKFza+avk321GQ5/WyeaBfBzp+W0zQFoJIJ2Suy0rEOwS+6C1ClnlOeNsCiwvrP60kc89K5LJn5srA+AlznOwFWZcyT1d7WAUxGQOVCI2MOUqyBzf4FFperRjmrhHiGuhjOZSB7UgDuFkuexdfDL2EtBnWDkRe3As6rO5OOp3B/VWWQ0etLkfryzPwMUlb8z1lMdNUdqIrb1IxrfB97SQQ+NxA/uuNn2HguubH7qekK5Enwmbbm+i1d8S6+VBxj2ReiRZFaMNeMI8q/QA==",
      "currency": "USD",
      "sandbox": true,
      "language": "en_US",
      "login_payload": "{\"signInReturnUrl\":\"https://example-site.com/amazon_pay/login/authorize/\",\"signInCancelUrl\":\"https://example-site.com/\",\"storeId\":\"amzn1.application-oa2-client.6df660f2573c40e8ba5815b43b8434da\",\"signInScopes\":[\"name\",\"email\"]}",
      "login_signature": "YuxfSQ+8sgH20B4fVisrpwpES67QTSDswat9vNZeQz3KqJ1MVH2E8JLgYltMDsjRq8eY4gCOZI/aW/sB5wyerdPdDke5LA9na9XliE+glODI2T58gOtx3eZcDl2IH7zUNHvicu/g3huYe6o/4KD5euRwiKhieZFChBeVxe8Z4i74weN/8SyYriJx/osI8CosihySDUk/wSGfuUlaxsJ9VgDzeaTdi6ANc7yWyskzKPQVEReDp5TO3d8x+e1BbQWBa0AjvZvj2zK7fHHzZklKNFoU0bSu4ZzBXvGalziR3Dpib2fJ9a2RZdPxtDuVi6lxgNbfQb/p89dKGjFmtLcmHA==",
      "merchant_id": "A1BIO10NFO603Q",
      "pay_only": true,
      "paynow_payload": "{\"webCheckoutDetails\":{\"checkoutMode\":\"ProcessOrder\",\"checkoutResultReturnUrl\":\"https://example-site.com/amazon_pay/checkout/completeSession/\",\"checkoutCancelUrl\":\"https://example-site.com/\"},\"storeId\":\"amzn1.application-oa2-client.6df660f2573c40e8ba5815b43b8434da\",\"paymentDetails\":{\"paymentIntent\":\"Authorize\",\"canHandlePendingAuthorization\":false,\"chargeAmount\":{\"amount\":10,\"currencyCode\":\"USD\"},\"presentmentCurrency\":\"USD\"},\"merchantMetadata\":{\"merchantReferenceId\":null,\"merchantStoreName\":null,\"customInformation\":\"Magento Version: 2.4.2-p1, Plugin Version: 5.11.1\"},\"addressDetails\":{\"name\":\"Jack Smith\",\"city\":\"Seattle\",\"postalCode\":\"98121\",\"countryCode\":\"US\",\"phoneNumber\":\"800-000-0000\",\"stateOrRegion\":\"WA\",\"addressLine1\":\"83034 Terry Ave\"}}",
      "paynow_signature": "HbCXNhALzzdVfAfMobMRSczijntjiLfpYzYNSpGJOcb9O48n2iDNdep0wQV73D1deO8oVVS4buOxPp7joNMwPy05D/ChQ1sepDMF8g37KNw2Ev77A73tOE77IXxDkKjnZiQVVJEaWxWhIVI3UqjKTTkCCWchEPwip3qhS/H+y7w6Y41uke4c0QPF1VQc5C8l/wzrlMuXqxqdbxQKW6yKniCeXDsEJGD+ja6nec5uiBIadQ9/ILyJOCbKefEckxAYBx3Ixur+znF17+9IEwUIwG+BuB5XSfxkP/G2F4N4doGVn5v20ATeF9qL6m20JsfOLAbF2aJKyNDe4/dNCt9nHA==",
      "public_key_id": "SANDBOX-AFJ2KQI25RZO2YTRPCHCGVJH"
    }
  }
}

Queries

`checkoutSessionDetails`

Address information and payment descriptor for the checkout session. Acceptable values for queryTypes are 'shipping', 'billing', and 'payment'.

Returns a CheckoutSessionDetailsOutput

Name	Description
`amazonSessionId` - `String!`
`queryTypes` - `[String!]`

Example

Query

query checkoutSessionDetails($amazonSessionId: String!, $queryTypes: [String!]) {
  checkoutSessionDetails(amazonSessionId: $amazonSessionId, queryTypes: $queryTypes) {
    response
  }
}

Variables

{
  "amazonSessionId": "f72f2b7a-5ffe-4544-918b-6a25ce481dce",
  "queryTypes": ["shipping"]
}

Response

{
  "data": {
    "checkoutSessionDetails": {
      "response": "{\"shipping\":[{\"city\":\"Chicago\",\"firstname\":\"Susie\",\"lastname\":\"Smith\",\"country_id\":\"US\",\"street\":[\"10 Ditka Ave\",\"Suite 2500\"],\"postcode\":\"60602\",\"company\":\"\",\"telephone\":\"800-000-0000\",\"region\":\"Illinois\",\"region_id\":\"23\",\"region_code\":\"IL\",\"email\":\"amzn+customer@example.com\"}]}"
    }
  }
}

Queries

`checkoutSessionSignIn`

Generates a customer bearer token for the Magento store based on a buyerToken returned from Amazon.

Returns a CheckoutSessionSignInOutput

Name	Description
`buyerToken` - `String!`

Example

Query

query checkoutSessionSignIn($buyerToken: String!) {
  checkoutSessionSignIn(buyerToken: $buyerToken) {
    customer_id
    customer_email
    customer_firstname
    customer_last
    customer_bearer_token
    message
    success
  }
}

Variables

{
  "buyerToken": "eyJ6aXAiOiJERUYiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoicXBtZWE2QmVHd3VlNk5GNDdSTkt6dyIsImFsZyI6IkExMjhHQ01LVyIsIml2IjoiNWNVcUUyeHU4X2Q0LWZDYyJ9.zh3wB8Q4xDniG7nP75AgJovXceqYbw-YIBF2QzrlWcw.U3Dcc6_7enIgdimr.aALvl6ZKMLqWUdQMbQ7eOqlWgAiT-k4laJbkIkFsUsA8PXo-v7GhDhveuzgwqdGXMczFXEZFFIM8y5NjL9HJbubHh3RMyhOchMeMHfXdPDkC2w-FsB3Z5EG4ufUzbi3zLz7YFKmdgTnz-1iKNfrnOWSdaJK6xwGBGuRjHt4uAg-YmKn37nTmd3Lcjhfb6D7IPA0aoIODvMRWGciGwYpYLXGJtxfjj_K1ZXntbXxWx4OohiUOyFaQs5Ds7pFw_hbD.hK_KHXuLQ4fdiFQxuN7gwA"
}

Response

{
  "data": {
    "checkoutSessionSignIn": {
      "customer_id": "201",
      "customer_email": "amzn+customer@example.com",
      "customer_firstname": "John",
      "customer_last": "Doe",
      "customer_bearer_token": "e8zxfpp9ljffsipjfbyl95oztaqls0y9",
      "message": null,
      "success": true
    }
  }
}

Mutations

`completeCheckoutSession`

Place an order in Magento and complete the Amazon checkout sesesion.

Returns a CompleteCheckoutSessionOutput

Name	Description
`cartId` - `String!`
`amazonSessionId` - `String!`

Example

Query

mutation completeCheckoutSession($cartId: String!, $amazonSessionId: String!) {
  completeCheckoutSession(cartId: $cartId, amazonSessionId: $amazonSessionId) {
    increment_id
    message
    success
  }
}

Variables

{
  "cartId": "d7Vw50EfbxdhgnoehD8ytqX8VM8nJL28",
  "amazonSessionId": "f72f2b7a-5ffe-4544-918b-6a25ce481dce"
}

Response

{
  "data": {
    "completeCheckoutSession": {
      "increment_id": "000000026",
      "message": null,
      "success": true
    }
  }
}

Mutations

`setCustomerLink`

Link an Amazon customer to an existing Magento store customer given the Amazon buyerToken and password for the store account. Genrates a customer bearer token on success.

Returns a SetCustomerLinkOutput

Name	Description
`buyerToken` - `String!`
`password` - `String!`

Example

Query

mutation setCustomerLink($buyerToken: String!, $password: String!) {
  setCustomerLink(buyerToken: $buyerToken, password: $password) {
    customer_id
    customer_email
    customer_firstname
    customer_last
    customer_bearer_token
    message
    success
  }
}

Variables

{
  "buyerToken": "eyJ6aXAiOiJERUYiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoicXBtZWE2QmVHd3VlNk5GNDdSTkt6dyIsImFsZyI6IkExMjhHQ01LVyIsIml2IjoiNWNVcUUyeHU4X2Q0LWZDYyJ9.zh3wB8Q4xDniG7nP75AgJovXceqYbw-YIBF2QzrlWcw.U3Dcc6_7enIgdimr.aALvl6ZKMLqWUdQMbQ7eOqlWgAiT-k4laJbkIkFsUsA8PXo-v7GhDhveuzgwqdGXMczFXEZFFIM8y5NjL9HJbubHh3RMyhOchMeMHfXdPDkC2w-FsB3Z5EG4ufUzbi3zLz7YFKmdgTnz-1iKNfrnOWSdaJK6xwGBGuRjHt4uAg-YmKn37nTmd3Lcjhfb6D7IPA0aoIODvMRWGciGwYpYLXGJtxfjj_K1ZXntbXxWx4OohiUOyFaQs5Ds7pFw_hbD.hK_KHXuLQ4fdiFQxuN7gwA",
  "password": "Password_ABC"
}

Response

{
  "data": {
    "setCustomerLink": {
      "customer_id": "201",
      "customer_email": "amzn+customer@example.com",
      "customer_firstname": "John",
      "customer_last": "Doe",
      "customer_bearer_token": "e8zxfpp9ljffsipjfbyl95oztaqls0y9",
      "message": null,
      "success": true
    }
  }
}

Mutations

`updateCheckoutSession`

Set transaction details on the Amazon checkout session and retrieve an amazonPayRedirectUrl to complete payment.

Returns an UpdateCheckoutSessionOutput

Name	Description
`cartId` - `String!`
`amazonSessionId` - `String!`

Example

Query

mutation updateCheckoutSession($cartId: String!, $amazonSessionId: String!) {
  updateCheckoutSession(cartId: $cartId, amazonSessionId: $amazonSessionId) {
    redirectUrl
  }
}

Variables

{
  "cartId": "d7Vw50EfbxdhgnoehD8ytqX8VM8nJL28",
  "amazonSessionId": "f72f2b7a-5ffe-4544-918b-6a25ce481dce"
}

Response

{
  "data": {
    "updateCheckoutSession": {
      "redirectUrl": "https://apay-us.amazon.com/checkout/processing?amazonCheckoutSessionId=3afdaa90-8b83-4c94-ba10-5a2ee0ef7433"
    }
  }
}

Types

`Boolean`

The Boolean scalar type represents true or false.

Example

true

Types

`CheckoutSessionConfigOutput`

For details on how to use these values to render the Amazon Pay button, see the Add the Amazon Pay Button documentation.

Field Name	Description
`button_color` - `String`
`checkout_payload` - `String`
`checkout_signature` - `String`
`currency` - `String`
`sandbox` - `Boolean`
`language` - `String`
`login_payload` - `String`
`login_signature` - `String`
`merchant_id` - `String`
`pay_only` - `Boolean`
`paynow_payload` - `String`
`paynow_signature` - `String`
`public_key_id` - `String`

Example

{
  "button_color": "Gold",
  "checkout_payload": "{\"webCheckoutDetails\":{\"checkoutReviewReturnUrl\":\"https://example-site.com/amazon_pay/login/checkout/\",\"checkoutCancelUrl\":\"https://example-site.com/\"},\"storeId\":\"amzn1.application-oa2-client.6df660f2573c40e8ba5815b43b8434da\"}",
  "checkout_signature": "BX/MOkF6pzmOp+PnznSPNmO9UdUCl3m7sRX92KJZOwlalKwfRx+AMDsG3T/LvGONe4MTkNKFza+avk321GQ5/WyeaBfBzp+W0zQFoJIJ2Suy0rEOwS+6C1ClnlOeNsCiwvrP60kc89K5LJn5srA+AlznOwFWZcyT1d7WAUxGQOVCI2MOUqyBzf4FFperRjmrhHiGuhjOZSB7UgDuFkuexdfDL2EtBnWDkRe3As6rO5OOp3B/VWWQ0etLkfryzPwMUlb8z1lMdNUdqIrb1IxrfB97SQQ+NxA/uuNn2HguubH7qekK5Enwmbbm+i1d8S6+VBxj2ReiRZFaMNeMI8q/QA==",
  "currency": "USD",
  "sandbox": true,
  "language": "en_US",
  "login_payload": "{\"signInReturnUrl\":\"https://example-site.com/amazon_pay/login/authorize/\",\"signInCancelUrl\":\"https://example-site.com/\",\"storeId\":\"amzn1.application-oa2-client.6df660f2573c40e8ba5815b43b8434da\",\"signInScopes\":[\"name\",\"email\"]}",
  "login_signature": "YuxfSQ+8sgH20B4fVisrpwpES67QTSDswat9vNZeQz3KqJ1MVH2E8JLgYltMDsjRq8eY4gCOZI/aW/sB5wyerdPdDke5LA9na9XliE+glODI2T58gOtx3eZcDl2IH7zUNHvicu/g3huYe6o/4KD5euRwiKhieZFChBeVxe8Z4i74weN/8SyYriJx/osI8CosihySDUk/wSGfuUlaxsJ9VgDzeaTdi6ANc7yWyskzKPQVEReDp5TO3d8x+e1BbQWBa0AjvZvj2zK7fHHzZklKNFoU0bSu4ZzBXvGalziR3Dpib2fJ9a2RZdPxtDuVi6lxgNbfQb/p89dKGjFmtLcmHA==",
  "merchant_id": "A1BIO10NFO603Q",
  "pay_only": true,
  "paynow_payload": "{\"webCheckoutDetails\":{\"checkoutMode\":\"ProcessOrder\",\"checkoutResultReturnUrl\":\"https://example-site.com/amazon_pay/checkout/completeSession/\",\"checkoutCancelUrl\":\"https://example-site.com/\"},\"storeId\":\"amzn1.application-oa2-client.6df660f2573c40e8ba5815b43b8434da\",\"paymentDetails\":{\"paymentIntent\":\"Authorize\",\"canHandlePendingAuthorization\":false,\"chargeAmount\":{\"amount\":10,\"currencyCode\":\"USD\"},\"presentmentCurrency\":\"USD\"},\"merchantMetadata\":{\"merchantReferenceId\":null,\"merchantStoreName\":null,\"customInformation\":\"Magento Version: 2.4.2-p1, Plugin Version: 5.11.1\"},\"addressDetails\":{\"name\":\"Jack Smith\",\"city\":\"Seattle\",\"postalCode\":\"98121\",\"countryCode\":\"US\",\"phoneNumber\":\"800-000-0000\",\"stateOrRegion\":\"WA\",\"addressLine1\":\"83034 Terry Ave\"}}",
  "paynow_signature": "HbCXNhALzzdVfAfMobMRSczijntjiLfpYzYNSpGJOcb9O48n2iDNdep0wQV73D1deO8oVVS4buOxPp7joNMwPy05D/ChQ1sepDMF8g37KNw2Ev77A73tOE77IXxDkKjnZiQVVJEaWxWhIVI3UqjKTTkCCWchEPwip3qhS/H+y7w6Y41uke4c0QPF1VQc5C8l/wzrlMuXqxqdbxQKW6yKniCeXDsEJGD+ja6nec5uiBIadQ9/ILyJOCbKefEckxAYBx3Ixur+znF17+9IEwUIwG+BuB5XSfxkP/G2F4N4doGVn5v20ATeF9qL6m20JsfOLAbF2aJKyNDe4/dNCt9nHA==",
  "public_key_id": "SANDBOX-AFJ2KQI25RZO2YTRPCHCGVJH"
}

Types

`CheckoutSessionDetailsOutput`

String representation of shipping/billing address or payment descriptor associated with an Amazon checkout session

Field Name	Description
`response` - `String!`

Example

{
  "response": "{\"shipping\":[{\"city\":\"Chicago\",\"firstname\":\"Susie\",\"lastname\":\"Smith\",\"country_id\":\"US\",\"street\":[\"10 Ditka Ave\",\"Suite 2500\"],\"postcode\":\"60602\",\"company\":\"\",\"telephone\":\"800-000-0000\",\"region\":\"Illinois\",\"region_id\":\"23\",\"region_code\":\"IL\",\"email\":\"amzn+customer@example.com\"}]}"
}

Types

`CheckoutSessionSignInOutput`

On failure, message will not be null, and customer_email may be non-null if a customer in the Magento store exists with the same email address as the Amazon account used for sign in.

Field Name	Description
`customer_id` - `String`
`customer_email` - `String`
`customer_firstname` - `String`
`customer_last` - `String`
`customer_bearer_token` - `String`
`message` - `String`
`success` - `Boolean`

Example

{
  "customer_id": "201",
  "customer_email": "amzn+customer@example.com",
  "customer_firstname": "John",
  "customer_last": "Doe",
  "customer_bearer_token": "e8zxfpp9ljffsipjfbyl95oztaqls0y9",
  "message": null,
  "success": true
}

Types

`CompleteCheckoutSessionOutput`

Contains success indicator, the ID of the placed order (increment_id), and if the order couldn't be placed, a message indicating why.

Field Name	Description
`increment_id` - `String`
`message` - `String`
`success` - `Boolean`

Example

{
  "increment_id": "000000026",
  "message": null,
  "success": true
}

Types

`SetCustomerLinkOutput`

On failure, message will be non-null to indicate what went wrong.

Field Name	Description
`customer_id` - `String`
`customer_email` - `String`
`customer_firstname` - `String`
`customer_last` - `String`
`customer_bearer_token` - `String`
`message` - `String`
`success` - `Boolean`

Example

{
  "customer_id": "201",
  "customer_email": "amzn+customer@example.com",
  "customer_firstname": "John",
  "customer_last": "Doe",
  "customer_bearer_token": "e8zxfpp9ljffsipjfbyl95oztaqls0y9",
  "message": null,
  "success": true
}

Types

`String`

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Types

`UpdateCheckoutSessionOutput`

Returns empty string until all checkout constraints have been satisfied. Then, an amazonPayRedirectUrl will be returned to direct the customer to for payment to be completed.

Field Name	Description
`redirectUrl` - `String`

Example

{
  "redirectUrl": "https://apay-us.amazon.com/checkout/processing?amazonCheckoutSessionId=3afdaa90-8b83-4c94-ba10-5a2ee0ef7433"
}