# Request Apple Pay payment session

When integrating Apple Pay in your own checkout on the web, you need to [provide merchant validation](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/providing_merchant_validation). This is normally done using Apple's [Requesting an Apple Pay Session](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/requesting_an_apple_pay_payment_session). The merchant validation proves to Apple that a validated merchant is calling the Apple Pay Javascript APIs.

To integrate Apple Pay via Mollie, you will have to call the Mollie API instead of Apple's API. The response of this API call can then be passed as-is to the completion method, `completeMerchantValidation`.

Before requesting an Apple Pay Payment Session, you must place the domain validation file on your server at: `https://[domain]/.well-known/apple-developer-merchantid-domain-association`. Without this file, it will not be possible to use Apple Pay on your domain.

Each new transaction requires a new payment session object. Merchant session objects are not reusable, and they expire after five minutes.

Payment sessions cannot be requested directly from the browser. The request must be sent from your server. For the full documentation, see the official [Apple Pay JS API](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api) documentation.

> 🔑 Access with
>
> [API key](/reference/authentication)
>
> [Organization access token with **payments.write**](/reference/authentication)
>
> [OAuth access with **payments.write**](/reference/authentication)

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Accepting payments",
    "version": "1.0.0",
    "license": {
      "name": "Attribution-NonCommercial-ShareAlike 4.0 International",
      "identifier": "CC-BY-NC-SA-4.0"
    }
  },
  "servers": [
    {
      "url": "https://api.mollie.com/v2"
    }
  ],
  "security": [
    {
      "apiKey": []
    },
    {
      "organizationAccessToken": []
    },
    {
      "oAuth": []
    }
  ],
  "paths": {
    "/wallets/applepay/sessions": {
      "post": {
        "summary": "Request Apple Pay payment session",
        "x-speakeasy-name-override": "request-apple-pay-session",
        "tags": [
          "Wallets API"
        ],
        "operationId": "request-apple-pay-payment-session",
        "security": [
          {
            "apiKey": []
          },
          {
            "organizationAccessToken": [
              "payments.write"
            ]
          },
          {
            "oAuth": [
              "payments.write"
            ]
          }
        ],
        "description": "When integrating Apple Pay in your own checkout on the web, you need to [provide merchant validation](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/providing_merchant_validation). This is normally done using Apple's [Requesting an Apple Pay Session](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/requesting_an_apple_pay_payment_session). The merchant validation proves to Apple that a validated merchant is calling the Apple Pay Javascript APIs.\n\nTo integrate Apple Pay via Mollie, you will have to call the Mollie API instead of Apple's API. The response of this API call can then be passed as-is to the completion method, `completeMerchantValidation`.\n\nBefore requesting an Apple Pay Payment Session, you must place the domain validation file on your server at: `https://[domain]/.well-known/apple-developer-merchantid-domain-association`. Without this file, it will not be possible to use Apple Pay on your domain.\n\nEach new transaction requires a new payment session object. Merchant session objects are not reusable, and they expire after five minutes.\n\nPayment sessions cannot be requested directly from the browser. The request must be sent from your server. For the full documentation, see the official [Apple Pay JS API](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api) documentation.\n\n> 🔑 Access with\n>\n> [API key](/reference/authentication)\n>\n> [Organization access token with **payments.write**](/reference/authentication)\n>\n> [OAuth access with **payments.write**](/reference/authentication)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "validationUrl": {
                    "type": "string",
                    "example": "https://apple-pay-gateway-cert.apple.com/paymentservices/paymentSession",
                    "description": "The validationUrl you got from the [ApplePayValidateMerchant event](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayvalidatemerchantevent).\n\nA list of all [valid host names](https://developer.apple.com/documentation/apple_pay_on_the_web/setting_up_your_server) for merchant validation is available. You should white list these in your application and reject any `validationUrl`s that have a host name not in the list."
                  },
                  "domain": {
                    "type": "string",
                    "description": "The domain of your web shop, that is visible in the browser's location bar. For example `pay.myshop.com`.",
                    "example": "pay.myshop.com"
                  },
                  "profileId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The identifier referring to the [profile](get-profile) this entity belongs to.\n\nMost API credentials are linked to a single profile. In these cases the `profileId` must not be sent in the creation request. For organization-level credentials such as OAuth access tokens however, the `profileId` parameter is required.",
                    "pattern": "^pfl_.+$",
                    "example": "pfl_5B8cwPMGnU"
                  }
                },
                "required": [
                  "validationUrl",
                  "domain"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The Apple Pay payment session object generated by Apple. This object, as mentioned in the Apple's Documentation, is opaque, so we are not defining a response schema.",
            "content": {
              "application/hal+json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {}
                },
                "examples": {
                  "request-apple-pay-payment-session-201-1": {
                    "summary": "The Apple Pay payment session object",
                    "value": {
                      "epochTimestamp": 1555507053169,
                      "expiresAt": 1555510653169,
                      "merchantSessionIdentifier": "SSH2EAF8AFAEAA94DEEA898162A5DAFD36E_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A9",
                      "nonce": "0206b8db",
                      "merchantIdentifier": "BD62FEB196874511C22DB28A9E14A89E3534C93194F73EA417EC566368D391EB",
                      "domainName": "pay.example.org",
                      "displayName": "Chuck Norris's Store",
                      "signature": "308006092a864886f7...8cc030ad3000000000000"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "The request contains issues. For example, if the validation URL is missing.",
            "content": {
              "application/hal+json": {
                "schema": {
                  "type": "object",
                  "description": "An error response object.",
                  "required": [
                    "status",
                    "title",
                    "detail",
                    "_links"
                  ],
                  "properties": {
                    "status": {
                      "type": "integer",
                      "description": "The status code of the error message. This is always the same code as the status code of the HTTP message itself.",
                      "minimum": 400,
                      "maximum": 599,
                      "example": 404
                    },
                    "title": {
                      "type": "string",
                      "description": "The HTTP reason phrase of the error. For example, for a `404` error, the `title` will be `Not Found`.",
                      "example": "Not Found"
                    },
                    "detail": {
                      "type": "string",
                      "description": "A detailed human-readable description of the error that occurred.",
                      "example": "The resource does not exist"
                    },
                    "field": {
                      "type": "string",
                      "description": "If the error was caused by a value provided by you in a specific field, the `field` property will contain the name of the field that caused the issue.",
                      "example": "description"
                    },
                    "_links": {
                      "type": "object",
                      "required": [
                        "documentation"
                      ],
                      "properties": {
                        "documentation": {
                          "type": "object",
                          "description": "The URL to the generic Mollie API error handling guide.",
                          "required": [
                            "href",
                            "type"
                          ],
                          "properties": {
                            "href": {
                              "type": "string",
                              "example": "https://docs.mollie.com/errors"
                            },
                            "type": {
                              "type": "string",
                              "example": "text/html"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "status": 422,
                  "title": "Unprocessable Entity",
                  "detail": "Apple is not able to verify your domain",
                  "_links": {
                    "documentation": {
                      "href": "...",
                      "type": "text/html"
                    }
                  }
                }
              }
            }
          }
        },
        "x-readme": {
          "code-samples": [
            {
              "language": "shell",
              "code": "curl -X POST https://api.mollie.com/v2/wallets/applepay/sessions \\\n    -H \"Authorization: Bearer live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM\" \\\n    -d \"domain=pay.mywebshop.com\" \\\n    -d \"validationUrl=https://apple-pay-gateway-cert.apple.com/paymentservices/paymentSession\""
            },
            {
              "language": "php",
              "code": "<?php\nuse Mollie\\Api\\MollieApiClient;\nuse Mollie\\Api\\Http\\Requests\\ApplePayPaymentSessionRequest;\n\n$mollie = new MollieApiClient();\n$mollie->setApiKey('live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM');\n\n$request = new ApplePayPaymentSessionRequest(\n    domain: 'pay.example.org',\n    validationUrl: 'https://apple-pay-gateway-cert.apple.com/paymentservices/paymentSession'\n);\n\n$session = $mollie->send($request);",
              "install": "composer require mollie/mollie-api-php"
            },
            {
              "language": "node",
              "code": "/*\nWe don't have a Node.js code example for this\nAPI call yet.\n\nIf you have some time to spare, feel free to\nshare suggestions on our Discord:\nhttps://discord.gg/VaTVkXB4aQ\n*/",
              "install": "npm install @mollie/api-client"
            },
            {
              "language": "python",
              "code": "'''\nWe don't have a Python code example for this\nAPI call yet.\n\nIf you have some time to spare, feel free to\nshare suggestions on our Discord:\nhttps://discord.gg/VaTVkXB4aQ\n'''",
              "install": "pip install mollie-api-python"
            },
            {
              "language": "ruby",
              "code": "# We don't have a Ruby code example for this\n# API call yet.\n#\n# If you have some time to spare, feel free to\n# share suggestions on our Discord:\n# https://discord.gg/VaTVkXB4aQ",
              "install": "gem install mollie-api-ruby"
            }
          ]
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "x-default": "live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM"
      },
      "organizationAccessToken": {
        "type": "http",
        "scheme": "bearer",
        "x-default": "access_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM"
      },
      "oAuth": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://my.mollie.com/oauth2/authorize",
            "tokenUrl": "https://api.mollie.com/oauth2/tokens",
            "scopes": {}
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false,
    "samples-languages": [
      "shell",
      "php",
      "node",
      "python",
      "ruby"
    ]
  }
}
```